Unity 使用包清单文件 (package.json) 来管理有关特定包的特定版本的信息。包清单始终位于包的根目录，并且包含有关包的重要信息，例如其注册名称和版本号。包清单还定义了与用户通信的有用信息，例如出现在 UI 中的用户友好名称、包的简要说明以及该包兼容的最低 Unity 版本。
包清单使用 JSON（JavaScript 对象表示法）语法来描述包中包含的内容。该文件的格式类似于 npm 的 package.json 格式，但是其某些属性使用了不同的语义。
Package Manager 读取此清单以确认包中包含的内容，如何解压缩其内容，以及在 Package Manager 窗口中向用户显示哪些信息。清单将此信息存储在一系列必需、强制和可选属性中。
这些属性是必需的。如果不存在这些属性，则注册表在发布包时会拒绝该包，或者 Package Manager 无法获取或加载该包。
| 属性 | JSON 类型 | 描述 |
|---|---|---|
| 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.
| 属性 | JSON 类型 | 描述 |
|---|---|---|
| displayName | String | 一个显示在 Unity Editor 中的用户友好名称（例如，显示在 Project Browser 中、Package Manager 窗口中，等等）。 例如，Unity Timeline、ProBuilder 或 In App Purchasing。 |
| description | String | 包的简要描述。这是在 Package Manager 窗口的详细信息视图中显示的文本。支持任何 UTF–8 字符代码。这意味着您可以使用特殊格式的字符代码，例如换行符 (\n) 和项目符号 (\u25AA)。 |
| unity | String | 指示包兼容的最低 Unity 版本。如果省略，则认为该包与所有 Unity 版本兼容。 预期格式为“<主要版本>.<次要版本>”（例如，2018.3）。要指向特定补丁，还要使用 unityRelease 属性。 注意：与 Unity 不兼容的包将不会出现在 Package Manager 窗口中。 |
这些属性是可选的，这意味着您可以省略它们。但如果存在，则必须具有有效值。
| 属性 | JSON 类型 | 描述 |
|---|---|---|
| unityRelease | String | Unity 版本的一部分，指示与包兼容的特定 Unity 版本。当更新的包需要在 Unity alpha/beta 开发周期中进行更改时（例如，如果该包需要新引入的 API，或该包使用的现有 API 以非向后兼容方式进行更改而不遵循 API Updater 规则），则可以使用此属性。 预期格式为“<更新><发行版本>”（例如 0b4）。 注意：如果省略 unity 属性，则此属性没有效果。 与 Unity 不兼容的包不会出现在 Package Manager 窗口中。 |
| dependencies | 对象 | 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 | 字符串数组 | Package Manager 搜索 API 使用的关键字数组。这可以帮助用户找到相关的包。 |
| type | String | 为 Package Manager 提供其他信息的常量。 保留仅供内部使用。 |
| author | 对象 | 包的创作者。 该对象包含一个必填字段 (name) 和两个可选字段 (email) 和 (url)。 例如： { "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:
| 递增该值： | 在这些条件下： | 示例： |
|---|---|---|
| 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. | 版本 1.3.0 和 1.3.1 应该可以互换，因为它们具有相同的 API，即使 1.3.1 包含 1.3.0 中不存在的错误修复。 |
通过遵循这些版本控制做法，Package Manager 可以自动解决冲突（如果可能），或将包升级到更高的向后兼容版本。
For more information, see the Semantic Versioning web site.