通过将玩家在不同平台上的帐户与主帐户关联，可实现以下功能：

• 在不同平台上自动识别玩家身份
• 通过单一跨平台物品库管理不同平台上的物品库

您可以使用演示场景来检查将平台帐户关联至一个预置发布商帐户项目中主帐户的效果。

要在演示项目中尝试帐户关联：

1. 前往您的Unity项目。
2. 将演示场景设置为通过平台帐户登录应用程序：
   1. 在主菜单中，前往Window > Xsolla > Edit Settings。
   2. 在Inspector面板设置以下参数：
      1. 指定Publishing platform。必须选择Xsolla和None以外的值。
      2. 更改Username from console。

3. 从Assets > Xsolla > DemoCommon > Scene文件夹中启动Xsollus演示场景。

4. 在演示场景中单击User account，然后单击Account linking。演示项目将在默认浏览器中打开，模拟在其他平台上启动应用程序。

5. 单击Create an account。

6. 指定邮箱和密码。单击Accept and create。

7. 在目录中选择一个商品，然后单击Buy on Xsolla。使用测试银行卡购买该商品。关闭付款凭证。

8. 单击屏幕顶部的邮件打开菜单。单击Inventory。确保所购商品出现在物品库中。

9. 单击Get code。在打开的窗口中单击Request the code。记录收到的帐户关联码。

10. 前往Unity中的演示场景。
11. 输入收到的帐户关联码（见步骤9），然后单击Confirm。

12. 平台帐户即与主帐户完成关联。请确保所购商品出现在Unity演示场景的物品库中。

13. 由于帐户现在已经与主帐户关联，因此可从该帐户获得帐户关联码。单击Get account link。记录收到的关联码。

14. 将演示场景设置为通过其他平台帐户登录应用程序（见步骤2）。Publishing platform需与步骤2中所选的平台不同。
15. 从Assets > Xsolla > DemoCommon > Scene文件夹启动Xsollus演示场景。

16. 确保玩家物品库为空。
17. 单击Account linking，然后留在Unity演示场景中。

18. 输入收到的帐户关联码（见步骤13），然后单击Confirm。

19. 该新平台的帐户即也与主帐户完成关联。请确保所购商品出现在Unity演示场景的物品库中。

请按照高级诀窍的说明为您的项目配置帐户关联。

提供有限奖励的免费战斗通行证可以面向所有玩家。免费通行证中不包含最终奖励。

此外，玩家也可以购买提供所有奖励（包括最终奖励）的付费通行证。

通行证全部进度分成几个等级。要解锁新等级并在通行证到期前打开最终奖励，玩家需获得相应的经验或购买等级。

演示项目提供了使用艾克索拉产品实现战斗通行证的示例。要试用战斗通行证：

1. 启动Xsollus演示场景。
2. 以演示用户身份登录或创建新用户。
3. 单击侧边栏菜单中的Battle pass。

要调整战斗通行证用于自己的项目：

1. 在项目中添加战斗通行证逻辑。
2. 创建奖励优惠券组。
3. 创建战斗通行证配置。
4. 创建战斗通行证商品项。
5. 创建升级商品项。

在项目中添加战斗通行证逻辑

战斗通行证的所有逻辑包含在BattlepassPage预制件中，分为以下几部分：

• ScriptHolders — 操作战斗通行证配置、商品和玩家信息的脚本
• UIScriptHolders — 玩家交互的脚本

要添加战斗通行证逻辑：

1. 在项目中，实例化BattlepassPage预制件。
2. 更改界面（可选）。
3. 修改信息存储逻辑。

创建奖励优惠券组

奖励可以是虚拟物品和虚拟货币套餐。

当前解决方案中，奖励以优惠券兑换的形式发放给玩家。要创建优惠券组：

1. 在发布商帐户中前往您的项目。
2. 创建用于奖励玩家的虚拟物品和虚拟货币套餐。
3. 对于每个奖励，按照以下建议设置优惠券活动：

1. • 根据战斗通行证预计的优惠券兑换数指定每个用户的兑换次数。战斗通行证中的一张优惠券可以兑换多次（例如针对不同的战斗通行证等级、付费版和免费版进行设置）。
   • 活动有效期必须与战斗通行证的有效期一致。

要创建战斗通行证配置，建议提前创建一个奖励列表，并为每个奖励指定：

• 优惠券码
• 虚拟物品或虚拟货币套餐SKU
• 奖励是否属于战斗通行证的某个指定等级
• 奖励是否属于免费版或付费版

创建战斗通行证配置

战斗通行证配置是一个包含以下信息的JSON文件：

• 战斗通行证名称
• 战斗通行证到期日
• 等级结构，指示免费版和付费版的奖励

JSON文件结构：

战斗通行证配置示例：

{
  "Name": "BP2021JAN",
  "ExpiryDate": "29-03-2021",
  "Levels": [
    {
      "Tier": 1,
      "Experience": 1000,
      "FreeItem": {
        "Sku": "Sku",
        "Quantity": 10,
        "Promocode": "HELLO_WORLD"
      },
      "PremiumItem": {
        "Sku": "Sku2",
        "Promocode": "HELLO_WORLD2"
      }
    },
    {
      "Tier": 2,
      "Experience": 1000
    },
    {
      "Tier": 3,
      "Experience": 1000
    }
  ]
}

创建战斗通行证商品项

战斗通行证商品项是战斗通行证配置的容器，用于决定玩家的付费状态（玩家是否购买了付费版）。

要创建一个战斗通行证商品项：

1. 在发布商帐户中前往您的项目。
2. 创建一个虚拟物品组并命名为#BATTLEPASS#。

3. 创建一个虚拟物品，包含以下参数：
   • 商品名称 — 配置中指定的商品通行证名称。
   • SKU — 战斗通行证ID。建议使用配置中指定的战斗通行证名称。
   • 商品属性 — 消耗品还是非消耗品。

1. • 价格 — 战斗通行证付费版的价格。可以用真实货币或虚拟货币进行设置。

1. • 组 — #BATTLEPASS#。

4. 向创建的虚拟物品中添加战斗通行证配置：
   1. 使用Get virtual item API调用获取JSON格式的当前商品描述。
   2. 使用在线服务或JavaScript中的JSON.stringify()方法将战斗通行证配置转换为一个字符串。
   3. 在商品描述中，在long_description参数的en对象中指定结果字符串。
   4. 使用Update virtual item API调用修改商品，在请求正文中指定更新后的商品描述。

战斗通行证商品项描述示例：

{
  "sku": "BP2021JAN",
  "name":{
    "en": "BP2021JAN"
  },
  "type": "virtual_good",
  "description":{
    "en": "BP2021JAN"
  },
  "image_url": "https://cdn3.xsolla.com/img/misc/images/7cb1c2b719af329a9bc1df994d58b749.png",
  "long_description": {
    "en": "{
                \"Name\":\"BP2021JAN\",
                \"ExpiryDate\":\"01-07-2021\",
                \"Levels\":
                    [
                        {
                            \"Tier\":1,
                            \"Experience\":100,
                            \"FreeItem\":
                                {
                                    \"Sku\":\"Bullets\",
                                    \"Promocode\":\"B2021S1FL1E100\",
                                    \"Quantity\":50
                                }
                        }
                    ]
            }"
  },
  "attributes":[
  ],
  "is_free": false,
  "order": 1,
  "groups":[
    "Battlepass"
  ],
  "regional_prices":[
  ],
  "prices":[
    {
      "amount": 1,
      "currency": "USD",
      "is_default": true,
      "is_enabled": true
    }
  ],
  "media_list":[
  ],
  "vc_prices":[
  ],
  "is_enabled": true,
  "is_show_in_store": true,
  "regions":[
  ],
  "inventory_options":{
    "consumable": false,
    "expiration_period": null
  }
}

创建升级商品项

当前战斗通行证解决方案可让玩家用真实货币或虚拟货币购买等级。等级的价格是固定的。玩家在当前等级获得的经验可转移到下一等级。

要创建升级商品项：

1. 在发布商帐户中前往您的项目。
2. 创建一个虚拟物品，包含以下参数：
   • 商品名称 — 升级商品项名称，格式为<battlepassname>_levelup_util，其中<battlepassname>是配置中指定的战斗通行证名称。
   • SKU — 建议使用配置中指定的战斗通行证名称。
   • 商品属性 — 消耗品还是非消耗品。
   • 价格 — 等级的价格。可用虚拟或真实货币进行设置。

1. • 组 — #BATTLEPASS#。

当前战斗通行证解决方案的细节

战斗通行证的显示逻辑

应用程序根据以下逻辑只显示一个战斗通行证：

• 如果存在一个或多个未到期的战斗通行证，应用程序显示离到期日最近的战斗通行证。
• 如果所有通行证都已到期，应用程序显示最后一个到期的战斗通行证。

示例1

当前日期：2021年3月4日。

各战斗通行证的到期日：2021年3月1日、2021年4月1日、2021年5月1日。

应用程序显示到期日为2021年4月1日的战斗通行证。

示例2

当前日期：2021年3月4日。

各战斗通行证的到期日：2021年2月1日、2021年3月1日。

应用程序显示到期日为2021年3月1日的战斗通行证。

信息存储逻辑

当前解决方案中，玩家战斗通行证的所有进度信息（等级、经验、收到的奖励等）存储在用户可编辑属性中。演示中包含读取和编辑这些属性的演示，见Character页面。

如果系统未找到所需的属性，将自动创建新属性。如果系统找到的属性不属于当前战斗通行证，将自动删掉这些属性。

为判断玩家的付费状态，将检查玩家物品库中存在的战斗通行证商品项。

SDK包含一个UI生成器，可使用它配置应用程序UI的视觉效果。

您可以通过编辑UI元素的视觉属性（颜色、精灵、字体）来更改UI。这些属性组合为一个主题。Unity主题和视觉组件由修饰器关联。更改视觉属性时，修饰器会更改Unity组件的视觉效果。

可使用小组件将UI元素替换为同一类型的其他元素。这些小组件以预制件形式存在，彼此独立并可轻松替换。

UI由2个独立部分组成：

• 负责操作视觉效果的主题编辑器。
• 负责操作预制件及完整替换UI元素的小组件编辑器。

使用主题

主题编辑器

要打开主题编辑器，请前往Unity编辑器主菜单，然后打开Window > Xsolla > UI Themes Editor。

主题编辑器UI包含以下组件：

• 包含主题名称的按钮，用于选择及应用主题。

• Refresh按钮 — 用于将主题属性或其更改应用至应用程序UI。
• Auto Refresh复选框 — 用于自动将主题属性或其更改应用至应用程序UI。
• Themes部分 — 包含现有主题列表。
• Colors部分 — 包含主题颜色列表。
• Sprites部分 — 包含主题精灵列表。
• Fonts部分 — 包含主题字体列表。

您可以对列表执行以下操作：

• 要添加新元素，单击列表下方的+图标。
• 要删除所选元素，单击列表下方的-图标。
• 要更改顺序，单击并按住=图标并将元素拖曳至列表中需要的位置。
• 要重命名元素，更改包含元素名称的字段中的文字。

属性值以标准Unity方式更改：

• 要更改颜色，单击属性字段并选择新值。
• 可通过以下方式之一更改字体或精灵：
  • 将资源拖曳至属性字段。
  • 单击⊙图标并选择资源。

主题库

主题库继承自ScriptableObject类，位于Resources/UIBuilder/ThemesLibrary目录。

将UI元素与主题关联

要让UI元素的视觉效果根据应用的主题进行更改：

1. 添加修饰器至对象并进行配置。
2. 添加属性提供器组件至对象并进行配置。

修饰器

修饰器是一种组件，用于将主题属性（颜色、精灵或字体）应用至标准Unity UI元素及进行更改。

修饰器包含属性ID（而非属性值），以及指向UI元素（图片或文本）的链接。可以说，修饰器就像主题和UI元素之间的接口。您可在Inspector面板中配置修饰器。

修饰器列表：

• ImageColorDecorator — 更改图片颜色
• ImageSpriteDecorator — 更改图片精灵
• TextFontDecorator — 更改文本颜色
• TextColorDecorator — 更改文本字体

如发生以下事件，修饰器将更改元素属性：

• 对象在主题编辑器中或游戏运行时期间被激活。
• 当前主题在编辑器中或游戏运行时期间发生更改。
• 在Inspector面板中对象属性和主题的关联发生更改。
• 主题编辑器中的属性值发生更改。
• 在主题编辑器中打开了对象预制件进行编辑。

要添加UI元素和主题间的关联，请执行以下操作：

1. 添加修饰器组件至对象。
2. 选择主题中属性的ID。

修饰器添加至对象后，它将尝试查找该对象上的所需UI对象并将其分配给Comp变量。

修饰器的应用示例：

ImageColorDecorator修饰器添加至图片对象。示例中颜色ID指定为Main Button。因此，将为图片使用主题中为Main Button指定的颜色。

玩家在玩游戏过程中用鼠标指向该对象或点击该对象时，修饰器可动态更改该组件的视觉效果。

要动态更改UI元素的视觉效果：

1. 将修饰器组件添加至对象。
2. 选择主题中属性的ID。
3. 将DecoratorPointerEvents组件添加至对象。该组件跟踪点击对象及鼠标指向对象的事件。
4. 在修饰器组件中，将TransitionMode变量的值更改为Override。
5. 将添加的DecoratorPointerEvents组件分配至修饰器的PointerEvents变量。
6. 要更改鼠标指向对象时的视觉效果：
   1. 勾选Override on hover复选框。
   2. 在复选框旁边的字段中，选择主题中属性的ID。
7. 要更改点击时的视觉效果：
   1. 勾选Override on press复选框。
   2. 在复选框旁边的字段中，选择主题中属性的ID。

修饰器应用动态更改视觉效果的示例：

ImageColorDecorator修饰器添加至图片对象。示例中颜色ID指定为Main Button，鼠标指向后的颜色ID指定为Main Button Hover。因此，将为图片使用主题中为Main Button指定的颜色。鼠标指向图片后，颜色将更改为主题中为Main Button Hover指定的颜色。

属性提供器

属性提供器是形式为主题属性容器的类，用于更便捷地关联用户代码和主题。

属性提供器列表：

• ColorProvider — 包含指向颜色属性的链接。
• SpriteProvider — 包含指向精灵属性的链接。
• FontProvider — 包含指向字体属性的链接。

所有属性提供器都有一个PropertyDrawer以便更方便地通过Inspector面板进行配置。

要在代码中配置属性提供器并获取属性值：

1. 添加属性提供器组件至对象。
2. 选择主题中属性的ID。

属性提供器配置示例：

3. 在脚本中，声明一个变量并向其分配一个属性提供器组件。
4. 要获取颜色值，请调用GetValue方法。

脚本示例：

public class ProviderExample : MonoBehaviour
{

  [SerializeField] private ColorPrivider ColorPrivider;

  private void Start()
  {
      Color color = ColorProvuder.GetValue();
  }

}

使用小组件

小组件编辑器

要打开小组件编辑器，请前往Unity编辑器主菜单，然后打开Window > Xsolla > UI Widgets Editor。

小组件编辑器UI包含以下组件：

• Refresh按钮 — 用于在预制件中应用小组件更改。
• Auto Refresh复选框 — 用于自动在预制件中应用小组件更改。
• Widgets部分 — 包含小组件列表。

您可以对小组件列表执行以下操作：

• 要添加新的小组件，单击列表下方的+图标。
• 要删除所选小组件，单击列表下方的-图标。
• 要更改顺序，单击并按住=图标并将元素拖曳至列表中需要的位置。
• 要重命名小组件，更改包含元素名称的字段中的文字。
• 可通过以下方式之一更改字体或精灵：

• 将预制件拖曳至包含小组件的字段。
• 单击⊙图标并选择预制件。

小组件库

小组件库继承自ScriptableObject类，位于Resources/UIBuilder/WidgetsLibrary目录。

将UI元素与小组件关联

要轻松替换UI元素，创建UI时应使用小组件容器而非直接使用小组件。这样即可通过配置容器创建的小组件来轻松更改同一类型的UI元素。如使用标准方法，则需手动替换所有小组件。

容器以子对象形式创建小组件对象并为其配置RectTransform类属性，让小组件填充容器的整个空间。

向UI元素对象添加容器组件时，该对象用作创建小组件的父对象。

如发生以下事件，容器将更改小组件属性：

• 在Inspector面板中对象属性和小组件间的关联发生更改。
• 小组件编辑器中的小组件预制件发生更改。

要关联UI对象和小组件：

1. 将WidgetContainer组件添加至对象。
2. 选择一个小组件ID。

使用小组件容器的示例：

对于WidgetA对象，示例中指定了ID为Red Button的小组件。因此，将使用编辑器中为Red Button小组件指定的预制件创建WidgetA对象。

UI生成器结构

运行时，UI生成器使用以下组件：

• UIProperty — 包含以下数据的对象：
  • 属性ID
  • 属性名称
  • 视觉数据（颜色、精灵、字体等）

• Theme — 主题组件。可通过主题更改UI的视觉效果。主题代表不同属性组合（颜色、精灵和字体）的集合。每个主题有一个名称和一个唯一标识符。您可以使用属性的ID访问主题属性。
• ThemesLibrary — 项目中存在的所有主题的库。它还包含当前主题的值，并提供更改该值的方法。
• ThemeDecorator — 引用主题属性并将属性值应用至标准Unity UI组件的MonoBehaviour类组件。例如ImageColorDecorator 修饰器可更改图片颜色。
• UIPropertyProvider — 授予主题属性访问权限的类。使用这些组件可以轻松将用户代码与主题数据关联。例如ColorProvider类用于向数据提供颜色。
• WidgetContainer — 用于更改整个小组件的MonoBehaviour类组件。
• WidgetsLibrary — 项目中存在的小组件集合。该组件包含所有小组件的列表并提供通过ID获取小组件的方法。