unity-packages-services

Unity 软件包和服务技能

Package Manager 工作流

Package Manager 窗口（通过 Window > Package Manager 打开）用于管理 UPM 软件包、功能集和资源包。

核心组件

• 导航面板：选择软件包上下文（Unity Registry、In Project、My Assets）
• 搜索框：按名称查找软件包
• 排序菜单：按名称或日期排序
• 筛选菜单：按类别或状态缩小结果范围
• 详情面板：查看软件包信息、版本、依赖项和变更日志
• 操作按钮：安装、移除、更新和自定义软件包

软件包状态

• 已发布：已针对当前 Unity 版本完成全面测试和验证
• 预发布：可用，但尚未完成全面验证
• 实验性：不稳定，并以警告徽标标示
• 内置：Unity 核心功能，可启用或禁用以减小构建体积
• 已弃用：不再维护

安装和管理软件包

通过 Package Manager UI

1. 打开 Window > Package Manager
2. 选择 Unity Registry 浏览可用软件包
3. 选择一个软件包并点击 Install
4. 若要更新：选择已安装的软件包，选择新版本，然后点击 Update
5. 若要移除：选择已安装的软件包，然后点击 Remove

通过 manifest.json

直接编辑 Packages/manifest.json 以添加依赖项：

{
    "dependencies": {
        "com.unity.addressables": "2.9.1",
        "com.unity.cinemachine": "3.1.0",
        "com.unity.inputsystem": "1.19.0"
    }
}

通过 Git URL

从 Git 仓库添加软件包：

{
    "dependencies": {
        "com.example.package": "https://github.com/user/repo.git#v1.0.0"
    }
}

也可通过 Package Manager UI 操作：点击 + 按钮 > Add package from git URL。

软件包自定义

• 复制到项目：通过 Manage 下拉菜单，可将 UPM 软件包复制到项目文件夹中进行修改
• 可变软件包：可直接编辑本地和嵌入式软件包的清单
• 内置软件包开关：禁用未使用的内置软件包以减小构建体积

Scoped Registries

Scoped Registries 使 Package Manager 能够与自定义软件包注册表服务通信，从而同时访问多个软件包集合。

主要用途

组织使用 scoped registries 在内部分发自定义软件包。

配置

添加到 Packages/manifest.json：

{
    "scopedRegistries": [
        {
            "name": "My Company Registry",
            "url": "https://npm.mycompany.com",
            "scopes": [
                "com.mycompany",
                "com.mycompany.tools"
            ]
        }
    ],
    "dependencies": {
        "com.mycompany.core-utils": "1.0.0"
    }
}

配置属性

属性	类型	描述
name	String	在 Package Manager UI 中显示的名称
url	String	兼容 npm 的注册表服务端点
scopes	Array	路由到此注册表的软件包命名空间

Scope 匹配规则

• 完全匹配的软件包名称优先
• 较长的命名空间匹配会覆盖较短的匹配
• 未映射的软件包默认使用 Unity 官方注册表
• 不支持通配符和 glob 模式
• Scope 使用反向域名表示法（com.example，而非 @scope）

注册表兼容性

注册表服务必须实现 /-/v1/search 或 /-/all 端点。并非所有 npm 注册表都兼容。

身份验证

对于受保护的注册表，请使用 npm 身份验证模式，在 Package Manager 用户配置文件中配置凭据。

必备软件包列表

Unity 6.3 LTS 随附 133 个已发布（已验证）软件包。完整的分类列表（含 ID 和版本）请参见 references/common-packages.md。

最常用软件包（快速参考）

软件包	ID	版本
Input System	com.unity.inputsystem	1.19
Addressables	com.unity.addressables	2.9
Cinemachine	com.unity.cinemachine	3.1
Burst	com.unity.burst	1.8
Collections	com.unity.collections	2.6
Entities	com.unity.entities	1.4
Timeline	com.unity.timeline	1.8
Netcode for GameObjects	com.unity.netcode.gameobjects	2.10
Localization	com.unity.localization	1.5
ProBuilder	com.unity.probuilder	6.0
Visual Scripting	com.unity.visualscripting	1.9

主要 UGS 包

包	ID
Authentication	com.unity.services.authentication
Cloud Save	com.unity.services.cloudsave
Analytics	com.unity.services.analytics
Cloud Code	com.unity.services.cloudcode
Economy	com.unity.services.economy
Leaderboards	com.unity.services.leaderboards
In-App Purchasing	com.unity.purchasing
Remote Config	com.unity.remote-config

Unity Gaming Services 概览

Unity Gaming Services（UGS）是一套用于游戏在线运营的后端服务。服务包括 Authentication、Cloud Save、Cloud Code、Analytics、Economy、Leaderboards、Friends、Multiplayer、Matchmaker 等。

开始使用 UGS

1. 在 Edit > Project Settings > Services 中将 Unity 项目关联到 UGS 项目
2. 通过 Package Manager 安装所需的服务包
3. 使用服务前，在代码中初始化服务

using Unity.Services.Core;
using UnityEngine;

public class ServicesInitializer : MonoBehaviour
{
    async void Start()
    {
        await UnityServices.InitializeAsync();
        Debug.Log("Unity Services initialized");
    }
}

Authentication

Authentication 服务提供玩家身份管理。安装 com.unity.services.authentication。

登录方式

• 匿名：无需凭据，自动生成玩家 ID
• 平台专属：Steam、PlayStation、Xbox、Apple、Google Play 等
• 自定义身份验证：OAuth/OIDC 集成
• Unity Player Accounts：跨平台身份

匿名登录

using Unity.Services.Authentication;
using Unity.Services.Core;
using UnityEngine;

public class AuthManager : MonoBehaviour
{
    async void Start()
    {
        await UnityServices.InitializeAsync();

        AuthenticationService.Instance.SignedIn += () =>
        {
            Debug.Log($"Signed in. Player ID: {AuthenticationService.Instance.PlayerId}");
        };

        await AuthenticationService.Instance.SignInAnonymouslyAsync();
    }
}

会话管理

• 会话会在应用重启后自动保留
• 访问令牌会自动刷新
• 同一设备上的玩家 ID 在不同会话中保持一致
• 将多种登录方式关联到一个玩家 ID，以实现跨平台游戏

主要 API

API	用途
AuthenticationService.Instance.SignInAnonymouslyAsync()	匿名登录
AuthenticationService.Instance.PlayerId	获取当前玩家 ID
AuthenticationService.Instance.IsSignedIn	检查登录状态
AuthenticationService.Instance.SignOut()	登出当前玩家
AuthenticationService.Instance.AccessToken	获取当前访问令牌

Cloud Save

Cloud Save 会将玩家数据和游戏状态持久化到云端。安装 com.unity.services.cloudsave。

数据类型

• 玩家数据：每位玩家的键值存储（设置、进度、库存）
• 游戏数据：所有玩家共享的数据（排行榜快照、游戏配置）

保存和加载数据

using Unity.Services.CloudSave;
using Unity.Services.Core;
using Unity.Services.Authentication;
using UnityEngine;
using System.Collections.Generic;

public class CloudSaveManager : MonoBehaviour
{
    async void Start()
    {
        await UnityServices.InitializeAsync();
        await AuthenticationService.Instance.SignInAnonymouslyAsync();

        // Save data
        var data = new Dictionary<string, object>
        {
            { "playerLevel", 5 },
            { "playerName", "Hero" },
            { "highScore", 12500 }
        };
        await CloudSaveService.Instance.Data.Player.SaveAsync(data);
        Debug.Log("Data saved to cloud");

        // Load data
        var keys = new HashSet<string> { "playerLevel", "highScore" };
        var loadedData = await CloudSaveService.Instance.Data.Player.LoadAsync(keys);

        if (loadedData.TryGetValue("playerLevel", out var levelItem))
        {
            int level = levelItem.Value.GetAs<int>();
            Debug.Log($"Player level: {level}");
        }
    }
}

主要 API

API	用途
CloudSaveService.Instance.Data.Player.SaveAsync()	保存玩家键值数据
CloudSaveService.Instance.Data.Player.LoadAsync()	按键加载玩家数据
CloudSaveService.Instance.Data.Player.LoadAllAsync()	加载所有玩家数据
CloudSaveService.Instance.Data.Player.DeleteAsync()	删除指定键

Analytics

Unity Analytics 用于跟踪玩家行为和游戏事件。安装 com.unity.services.analytics。

事件类型

• 标准事件：预定义事件（例如，关卡完成、交易）
• 自定义事件：由开发者定义并带有自定义参数的事件

记录事件

using Unity.Services.Analytics;
using Unity.Services.Core;
using UnityEngine;

public class AnalyticsManager : MonoBehaviour
{
    async void Start()
    {
        await UnityServices.InitializeAsync();
        AnalyticsService.Instance.StartDataCollection();
    }

    public void RecordLevelComplete(int level, float time)
    {
        var parameters = new Dictionary<string, object>
        {
            { "levelIndex", level },
            { "completionTime", time },
            { "livesRemaining", 3 }
        };
        AnalyticsService.Instance.CustomData("levelComplete", parameters);
    }

    public void RecordPurchase(string itemId, float price)
    {
        var parameters = new Dictionary<string, object>
        {
            { "itemId", itemId },
            { "price", price },
            { "currency", "USD" }
        };
        AnalyticsService.Instance.CustomData("itemPurchased", parameters);
    }
}

数据隐私

• 获得用户同意后，调用 AnalyticsService.Instance.StartDataCollection()
• 遵守 GDPR、CCPA 和平台隐私要求
• 如果用户撤回同意，请使用 AnalyticsService.Instance.StopDataCollection()

主要 API

API	用途
AnalyticsService.Instance.StartDataCollection()	开始收集分析数据
AnalyticsService.Instance.StopDataCollection()	停止收集数据
AnalyticsService.Instance.CustomData()	记录带参数的自定义事件
AnalyticsService.Instance.Flush()	强制发送排队的事件

常见模式

服务初始化模式

using Unity.Services.Core;
using Unity.Services.Authentication;
using UnityEngine;

public class GameBootstrap : MonoBehaviour
{
    async void Awake()
    {
        try
        {
            await UnityServices.InitializeAsync();
            await AuthenticationService.Instance.SignInAnonymouslyAsync();
            Debug.Log($"Player ID: {AuthenticationService.Instance.PlayerId}");

            // Now safe to use Cloud Save, Analytics, etc.
        }
        catch (ServicesInitializationException e)
        {
            Debug.LogError($"Services failed to initialize: {e.Message}");
        }
        catch (AuthenticationException e)
        {
            Debug.LogError($"Authentication failed: {e.Message}");
        }
    }
}

通过脚本管理包

#if UNITY_EDITOR
using UnityEditor.PackageManager;

public static class PackageHelper
{
    // Install: Client.Add("[email protected]");
    // Remove:  Client.Remove("com.unity.cinemachine");
    // List:    Client.List();  // Returns ListRequest, poll IsCompleted
}
#endif

反模式

1. 使用任何服务前未初始化 UnityServices。 请务必先调用 UnityServices.InitializeAsync()。所有 UGS 服务都依赖此操作。

2. 使用 Cloud Save 或其他与玩家绑定的服务前未进行身份验证。 访问玩家个人数据前必须进行身份验证。

3. 未经用户同意就收集分析数据。 仅在获得同意后调用 StartDataCollection()。违反隐私法规可能导致法律诉讼和平台下架。

4. 未加密就将敏感数据存储在 Cloud Save 中。 Cloud Save 是键值存储，并非安全保险库。保存前请加密敏感数据。

5. 未检查兼容性就在 manifest.json 中硬编码包版本。 请务必确认包版本与 Unity 版本兼容。使用 Package Manager UI 检查已验证的版本。

6. 生产环境中通过 git URL 安装包，却未固定版本或标签。 请务必指定标签或提交哈希（例如 #v1.0.0），以避免意外的破坏性变更。

7. 未妥善处理服务错误。 UGS 调用是异步网络操作。请务必使用 try/catch 包装，并处理离线情况。

8. 动态内容使用 Resources.Load，而非 Addressables。 构建后无法更新 Resources 文件夹中的内容。Addressables 支持远程内容更新。

9. 添加作用域过宽的 scoped registry。 com 之类的宽泛作用域会将许多包路由到自定义 registry。请使用 com.mycompany 之类的具体作用域。

API 速查

API	用途
UnityServices.InitializeAsync()	初始化所有 UGS 服务
AuthenticationService.Instance	访问身份验证服务
CloudSaveService.Instance	访问 Cloud Save 服务
AnalyticsService.Instance	访问分析服务
UnityEditor.PackageManager.Client.Add()	通过脚本安装包
UnityEditor.PackageManager.Client.List()	列出已安装的包
UnityEditor.PackageManager.Client.Remove()	通过脚本移除包

相关技能

• unity-foundations — Unity 核心概念、项目设置和 C# 脚本基础
• unity-platforms — 平台适配、构建配置文件和特定平台优化

其他资源

• 包概览
• Package Manager 窗口
• 作用域注册表
• 已发布包列表
• Unity Gaming Services
• 身份验证
• Cloud Save
• 分析