Unity uses the package manifest file (package.json) to manage information about a specific version of a specific package. The package manifest is always at the root of the package and contains crucial information about the package, such as its registered name and version number. It also defines useful information to communicate to the user, such as a user-friendly name that appears in the UI and a brief description of the package, as well as the earliest version of Unity the package is compatible with.
The package manifest uses the JSON (JavaScript Object Notation) syntax to describe what the package contains. The file’s format is similar to npm’s package.json format, but uses different semantics for some of its attributes.
The Package Manager reads this manifest to find out what the package contains, how to unpack its contents, and what information to show the user in the Packages window. The manifest stores this information in a series of required, mandatory, and optional attributes.
These attributes are required. If they are not present, either the registry refuses the package when it is published, or the Package Manager cannot fetch or load the package.
| Attribute | JSON Type | 描述 |
|---|---|---|
| name | String | The officially registered package name. This name must conform to the Unity Package Manager naming convention, which uses reverse domain name notation. The name must: - Start with com.<company-name>. - Have a length of 50 characters or less to appear in the Editor; otherwise, 214 characters or less. - Contain only lowercase letters, digits, hyphens (-), underscores (_), and periods (.) - To indicate nested namespaces, suffix the namespace with an additional period. For example, com.unity.timeline is the name of the package that implements Timeline in Unity. NOTE: This is a unique identifier, not the user-friendly name that appears in the list view on the Package Manager window. |
| version | string | The package version number (**’MAJOR.MINOR.PATCH“**). This value must respect semantic versioning. For more information, see Package version. For example, ”3.2.1" indicates that this is the 3rd major release, the 2nd minor release, and the first patch. |
These attributes are technically optional, and the Package Manager can still install them in a Projects even if they do not contain valid values or are missing. However, you should give these attributes values in order to make your package easily discoverable and provide package consumers with a better experience.
| Attribute | JSON Type | 描述 |
|---|---|---|
| displayName | String | A user-friendly name to appear in the Unity Editor (for example, in the Project Browser, the Package Manager window, etc.). For example, Unity Timeline, ProBuilder, In App Purchasing. |
| description | String | A brief description of the package. This is the text that appears in the details view of the Packages window. Any UTF–8 character code is supported. This means that you can use special formatting character codes, such as line breaks (\n) and bullets (\u25AA). |
| unity | String | Indicates the lowest Unity version the package is compatible with. If omitted, the package is considered compatible with all Unity versions. The expected format is “<MAJOR>.<MINOR>” (for example, 2018.3). To point to a specific patch, use the unityRelease attribute as well. NOTE: A package that is not compatible with Unity will not appear in the Packages window. |
These attributes are optional, meaning that you can omit them. However, if they are present, they must have a valid value.
| Attribute | JSON Type | 描述 |
|---|---|---|
| unityRelease | String | Part of a Unity version indicating the specific release of Unity that the package is compatible with. You can use this attribute when an updated package requires changes made during the Unity alpha/beta development cycle (for example, if it needs newly introduced APIs, or uses existing APIs that changed in a non-backward-compatible way without API Updater rules). The expected format is “<UPDATE><RELEASE>” (for example, 0b4). NOTE: If you omit the unity attribute, this attribute has no effect. A package that is not compatible with Unity does not appear in the Packages window. |
| dependencies | Object | A map of package dependencies. Keys are package names, and values are specific versions. They indicate other packages that this package depends on. NOTE: The Package Manager does not support range syntax, only SemVer versions. |
| keywords | Array of Strings | An array of keywords used by the Package Manager search APIs. This helps users find relevant packages. |
| type | String | A constant that provides additional information to the Package Manager. Reserved for internal use. |
| author | Object | Author of the package. This object contains one required field (name) and two optional fields (email) and (url). For example: { "name" : "John Doe","email" : "john.doe@example.com","url" : "http://john.doe.example.com/"}
|
{
"name": "com.unity.example",
"version": "1.2.3",
"displayName": "Package Example",
"description": "This is an example package",
"unity": "2019.1",
"unityRelease": "0b5",
"dependencies": {
"com.unity.some-package": "1.0.0",
"com.unity.other-package": "2.0.0"
},
"keywords": [
"keyword1",
"keyword2",
"keyword3"
],
"author": {
"name": "Unity",
"email": "unity@example.com",
"url": "https://www.unity3d.com"
}
}
Package versioning must follow Semantic Versioning (SemVer). SemVer is a versioning strategy that allows package authors to provide information on the type of changes included in a given version, compared to the previous version, in a format that automated tools can use.
SemVer expresses versions as MAJOR.MINOR.PATCH, and provides a definition for compatibility using these guidelines:
| Increment this value: | Under these conditions: | Example: |
|---|---|---|
| MAJOR | There is at least one breaking change. Neither version of the package can be substituted for the other. |
Versions 1.2.3 and 2.0.0 are not compatible and cannot be used interchangeably without any risk. |
| MINOR (same MAJOR value) | The highest MINOR introduces functionality in a backward-compatible way. | Use Version 1.3.0 to fulfill a dependency on 1.2.0 because 1.3.0 is backward-compatible. You can’t use 1.2.0 to fulfill a dependency on 1.3.0. |
| PATCH (same MAJOR.MINOR values) | The highest PATCH introduces bug fixes without changing the API at all, in a backward-compatible way. | Versions 1.3.0 and 1.3.1 should be interchangeable because they have the same API, even though 1.3.1 contains a bug fix not present in 1.3.0. |
Following these versioning practices allows the Package Manager to automatically solve conflicts (when possible), or upgrade packages to newer, backward-compatible versions.
For more information, see the Semantic Versioning web site.