UPM自定义资源包及相关规范

创建时间：2020/9/22 17:06

UPM自定义资源包及相关规范

ByPrin@UWA

• UPM自定义资源包及相关规范
  • UPM资源包介绍
    • 文件布局
    • Package manifest
      • Name
      • Display Name
      • 版本号规范
      • the lowest Unity version
      • Package manifest example
    • Assembly definition
    • LICENSE相关（暂时忽略）
  • 步骤
    • 1. 按照规范创建Package
    • 分发
      • zip
      • Git代码库分发
  • README文档
  • Changelog规范
  • Semantic Versioning规范
  • Ref

UPM资源包介绍

作用：给Unity Package Manager制作自定义资源包，并上传至Github托管。使用PackageManager设定项目的依赖、解析资源包依赖、下载添加需要的资源包，将内容整合到项目中，以便在其他项目中使用，并与其他开发者共享。 常用于

• 编辑器工具——文本编辑器、动画查看器或文本框架、Physics API、图形管线

• 内容库——纹理和动画资源集合

Unity 2018.3 及之后版本, Unity Package Manager (UPM) 开始支持 Git

文件布局

UPM资源包是一个按特定标准排列的文件夹，是一个包含各种功能、资源的容器。必须遵循Unity的包格式标准才能正确运行（推荐的文件布局和版本号格式）。

class Program
{
    static void Main(string[] args)
    {
        dynamic dyn = 1;
        object obj = 1;
        dyn = dyn + 3;
        //obj = obj + 3; 报错

        // Rest the mouse pointer over dyn and obj to see their
        // types at compile time.
        System.Console.WriteLine(dyn.GetType());
        System.Console.WriteLine(obj.GetType());
    }
}

文件夹名称以~结尾不会显示在Editor的Project窗口

Package manifest

可以在Unity - Inspector面板填写

crucial information

• its registered name

• version number To User:

• a user-friendly name that appears in the list view on the Package Manager window.

• a brief description of the package

• the earliest version of Unity the package is compatible with.

Name

This name must conform to the Unity Package Manager naming convention, which uses reverse domain name notation.

• Start with com.<company-name>.

• Contain only lowercase letters , digits, hyphens (-), underscores (_), and periods (.)

Display Name

是在Package Manager窗口显示给用户的名称，也是在Project窗口显示的包的Root文件夹的名称。

版本号规范

Major.Minor.Patch

the lowest Unity version

If omitted, the package is considered compatible with all Unity versions. A package that is not compatible with Unity will not appear in the Package Manager window.

Package manifest example

在包的根目录下创建文件package.json，只要格式符合规范，就能被UPM识别

class Program
{
    static void Main(string[] args)
    {
        dynamic dyn = 1;
        object obj = 1;
        dyn = dyn + 3;
        //obj = obj + 3; 报错

        // Rest the mouse pointer over dyn and obj to see their
        // types at compile time.
        System.Console.WriteLine(dyn.GetType());
        System.Console.WriteLine(obj.GetType());
    }
}

Assembly definition

Assembly definition files are the Unity equivalent to a C# project in the .NET ecosystem. You must set explicit references in the assembly definition file to other assemblies (whether in the same package or in external packages).

命名规则： Editor/MyCompany.MyFeature.Editor.asmdef Runtime/MyCompany.MyFeature.Runtime.asmdef

CompanyName.FeatureName与package.json文件一致 文件的名称与文件中的”name”一致

使用asmdef的优势

• 更短的编译时间

• 发挥访问修饰符”internal”的作用

• 允许使用 unsafe code

• .dll 文件可以指定特定的程序集引用。

一些注意事项：

1. Editor 文件夹下的 AssemblyDefinition 中 Platform 只能选择 Editor，并且 Reference 必须添加上 Runtime 中的那个 AssemblyDefiniion

LICENSE相关（暂时忽略）

推荐添加Third Party Notices.md 和 LICENSE.md

• LICENSE.md：例如以MIT许可证为准的开源许可证MD文件

步骤

1. 按照规范创建Package

分发

zip

压缩为zip文件 Unity Package Manager窗口通过Add Package from Disk添加

Git代码库分发

添加到Git仓库中，包括meta文件

下载方式（使用者必须安装git）

• 在PackageManager中通过Git URL直接下载

class Program
{
    static void Main(string[] args)
    {
        dynamic dyn = 1;
        object obj = 1;
        dyn = dyn + 3;
        //obj = obj + 3; 报错

        // Rest the mouse pointer over dyn and obj to see their
        // types at compile time.
        System.Console.WriteLine(dyn.GetType());
        System.Console.WriteLine(obj.GetType());
    }
}

README文档

Developer package documentation. This is generally documentation to help developers who want to modify the package or push a new change on the package master source repository.

Changelog规范

You can update the CHANGELOG.md file every time you publish a new version. Every new feature or bug fix should have a trace in this file.

Added for new features. Changed for changes in existing functionality. Deprecated for soon-to-be removed features. Removed for now removed features. Fixed for any bug fixes. Security in case of vulnerabilities.

轻量级的使用Fixed和Features就足够了

例如：

class Program
{
    static void Main(string[] args)
    {
        dynamic dyn = 1;
        object obj = 1;
        dyn = dyn + 3;
        //obj = obj + 3; 报错

        // Rest the mouse pointer over dyn and obj to see their
        // types at compile time.
        System.Console.WriteLine(dyn.GetType());
        System.Console.WriteLine(obj.GetType());
    }
}

原则 Changelogs are for humans, not machines.

• There should be an entry for every single version.

• The same types of changes should be grouped.

• Versions and sections should be linkable.

• The latest version comes first.

• The release date of each version is displayed.

• Mention whether you follow Semantic Versioning.

Semantic Versioning规范

MAJOR.MINOR.PATCH

• MAJOR introduces one or more breaking changes

• MINOR introduces one or more backward-compatible API changes

• PATCH only introduces bug fixes with no API changes at all

When you begin to develop a package, start the version number at 0.1.0. The MAJOR version number 0 is reserved for packages in their initial development phase. During initial development, package APIs change often, frequently in a breaking manner, so keep the MAJOR version number at 0 until you consider your package stable enough and ready for use in production.

PS: 该规范主要在开发提供给用户的API时有重要作用。先不深究，大致按照此标准进行即可。

Ref

https://docs.unity.cn/2019.4/Documentation/Manual/CustomPackages.html https://keepachangelog.com/en/1.0.0/ https://semver.org/ https://www.jianshu.com/p/153841d65846