plugin.gamecircle

概述

GameCircle 插件使基于 Android 的 Corona 游戏能够访问 Amazon GameCircle 服务中的所有功能。使用 Amazon 服务器记录玩家成就，维护排行榜，并利用 Amazon 强大的 Whispersync for Games 功能在云中维护游戏数据。

设置

要使用 GameCircle 插件，您必须首先在 Amazon 服务器上为您的游戏创建 GameCircle 配置并使用数据填充它。

为此，请访问 Amazon 的 GameCircle API 文档。您可能需要阅读并四处搜索以了解 GameCircle 的一般工作原理，因为此插件只是 Lua 游戏代码与基于 Java 的GameCircle API 之间的媒介。

• Amazon 的 GameCircle 和 Corona

• Amazon GameCircle API 首页

• Amazon 的 GameCircle 设置指南

完成所有这些操作后，设置成就、排行榜和安全配置文件后，您需要执行最后一步。您需要获取与您的包名称和安全配置文件关联的 API 密钥。它通常是一个很长的字母和数字字符串，没有空格。它可以在应用程序安全配置文件的“Kindle/Android 设置”下找到。您需要将整个密钥复制并粘贴到一个空文本文件中，然后将该文本文件另存为 `api_key.txt` 到您的项目目录中。这就是 GameCircle API 向 Amazon 服务器标识自身的方式；没有有效的 API 密钥，该插件将无法工作。生成 API 密钥的具体说明可以在此处找到。

语法

在 Amazon 服务器上设置好游戏并复制 API 密钥后，您就可以在应用程序中包含并集成 GameCircle 插件了。一开始，您只需调用两个函数即可使 GameCircle 为您工作。

local gamecircle = require( "plugin.gamecircle" )

gamecircle.Init( true, true, true )

`require()` 行将 GameCircle 插件加载到您的应用程序中。`Init()` 函数是您告诉插件您希望向用户提供 GameCircle 的哪三个功能的方式。除此之外，请阅读下面的功能相关部分以获取函数文档，并且不要忘记阅读 GameCircle API，以便了解其 SDK 在幕后的运行方式。

陷阱 / 提示

这些是关于 GameCircle 插件和 GameCircle SDK 需要了解的重要事项。

1. 此插件仅适用于 Android。虽然代码可以在 Corona 模拟器中编译，但对 GameCircle 插件的所有函数调用都将返回 `nil`。这是设计使然，因为 GameCircle SDK 本身仅适用于 Android。

2. 要与您在草稿模式下创建的排行榜和成就进行交互，您需要将您正在测试的任何 GameCircle 玩家个人资料名称添加到测试帐户白名单中。查看 GameCircle 的测试您的游戏文档，了解如何执行此操作。

3. Whispersync for Games 数据无法删除（Amazon 施加的限制），因此在为 Whispersync for Games 开发时要小心，并确保在开发过程中使用 GameCircle 测试帐户，以确保您不会污染与您的个人或您公司 Amazon 帐户关联的 Whispersync 数据垃圾数据.

4. 如果您已经熟悉 Amazon 的 Whispersync for Games，请务必阅读有关此插件如何模拟 Whispersync 使用数据对象来设置和检索数据的文档。无法在不破坏预期功能的情况下将 Whispersync 使用的数据对象直接拉入 Lua。因此，该插件近似地实现了该功能。您可以在 Whispersync 部分阅读更多内容。

5. 该插件尝试在 GameCircle SDK 提供的功能之间保持一对一的关系。如果您对特定功能和/或函数提供的数据的意义感到好奇，请查看 Amazon 的 GameCircle 文档。

通用函数

这些函数提供了一些通用功能，它们要么与特定的 GameCircle 功能无关，要么对所有三个功能都有用。

成就函数

这些函数提供对 Amazon GameCircle API 的成就功能的访问。请记住在尝试使用这些函数之前在 Amazon 服务器上设置成就。

成就属性

这些是 Achievement 函数直接或通过函数回调返回的数据结构。

排行榜函数

这些函数提供对 Amazon GameCircle API 的排行榜功能的访问。请记住在尝试使用这些函数之前在 Amazon 服务器上设置排行榜。

排行榜属性

这些是 Leaderboard 函数直接或通过函数回调返回的数据结构。

Whispersync 常规信息

本节中的信息主要针对以前使用过基于 Java 的 GameCircle SDK 的用户。它提供了有关 GameCircle SDK 和此插件的实现之间重要区别的信息。

与 Amazon 的 GameCircle SDK 相比，此插件在 Whispersync for Games 的实现方面差异最大。Whispersync 功能仍然具有相同级别的功能和易用性，但由于 Java 和 Lua 作为编程语言之间的根本差异，该插件必须略有不同。

在插件中，您使用函数将表示一段数据的对象放入 Whispersync 的系统中。请参阅以下在 Java 中完成的示例

//Java Example using GameCircle SDK
String key = "level6LocalHighScore"
GameDataMap gameDataMap = AmazonGamesClient.getWhispersyncClient().getGameData();
SyncableNumber syncNumber = gameDataMap.getHighestNumber(key);
syncNumber.Set(8675309)

在上面的示例中，作为开发人员，您可以只保留我们刚刚创建的 `syncNumber` 并在需要时不断为其分配新值。然后，Whispersync 的系统将在后台处理将更新的数据保存在本地和云中。此功能无法在 Corona 的 Lua 语言中复制，因为无法在不破坏其内部功能的情况下将 GameCircle SDK 对象（如 `SyncableNumber`）转换为 Lua 表/对象。

因此，此插件的工作原理类似于 C++ 和 C# 等语言中的字典/哈希表。以下是使用此插件在 Lua 中完成的上述相同示例

--Lua example using this GameCircle plugin
local gamecircle = require( "plugin.gamecircle" )
local key = "level6LocalHighScore"
gamecircle.Init( false, false, true )
gamecircle.Whispersync.SetHighestNumber( key, 8675309, "INT" )

从插件中可以看出，您无需使用键来获取对 SyncableNumber 的引用，而是使用键通过 SetHighestNumber() 函数来设置值。从本质上讲，这是此插件与 GameCircle SDK 之间的唯一区别。您需要使用类似字典的函数来访问数据，而不是获取表示数据的对象并对其进行更新。Whispersync 的系统仍然会在本地和云端执行数据的后台保存和更新。作为开发者，您仍然可以通过提供回调函数来挂钩到 Whispersync 的事件系统。

GameData 对象的处理方式也存在关键区别，但这将在下面的 GameData 导航部分中讨论。

Whispersync for Games 函数

这些函数允许设置、获取和操作使用 Whispersync for Games 存储的数据。有关 GameCircle 如何使用 Whispersync for Games 的更多信息，请参阅亚马逊的 [Whispersync 的 GameCircle 文档] (https://developer.amazon.com/public/apis/engage/gamecircle/docs/whispersync)。

Whispersync 属性

这些是由 Whispersync 函数直接或通过函数回调返回的数据结构。

Whispersync 游戏数据导航函数

在 GameCircle SDK 中使用 Whispersync for Games 时，所有数据都存储在根 GameData 对象中。如果您没有触及下面的任何函数，那么上面的所有数据设置函数都会将其数据与该根 GameData 对象关联。但是，Whispersync 允许该根 GameData 对象具有子 GameData 对象。像树一样工作，这允许您作为开发者在 Whispersync 中分离数据集。一个常见的例子是为游戏的每个关卡或玩家拥有的每个角色设置一个子 GameData 对象，如果多个存档/角色是您的游戏/应用程序设计的一部分的话。

在此插件中，可以通过以下函数和在 GameData 树中上下移动的概念来访问此功能。向下移动可以让您更深入地了解树。例如，从根 GameData 对象移动到名为“Level 1”的子对象，该对象旨在保存与游戏第一关相关的信息。如果您需要从 GameData“Level 1”获取到“Level 2”，则需要返回到树的根，然后向下移动到“Level 2”数据。如果您难以想象这些连接和方法，请对编程中的树数据结构进行一些研究。

项目设置

要使用此插件，请在 build.settings 的 plugins 表中添加一个条目。添加后，构建服务器将在构建阶段集成插件。

settings =
{
    plugins =
    {
        ["plugin.gamecircle"] =
        {
            publisherId = "COM_INNOVATIVELEISURE"
        },
    },
}

Solar2D Native

插件的 Solar2D Native 版本可以通过与普通版本类似的方式获得。您必须下载插件的软件包并包含其中包含的四个 .jar 文件。

• AmazonInsighss-android-sdk-2.1.26.jar
• gamecirclesdk.jar
• login-with-amazon-sdk.jar
• plugin.gamecircle.jar

除了在 Solar2D Native 项目的相应部分中包含这四个 .jar 文件之外，您还必须对 Android 清单进行以下更改。

如果您的应用中还没有以下两个用户权限，则必须将它们添加到您的应用中。

• “android.permission.INTERNET”
• “android.permission.ACCESS_NETWORK_STATE”

您还必须将以下内容添加到您的清单中，并将 "@USER_ACTIVITY_PACAKGE@" 替换为您在清单文件顶部附近设置的软件包标识符。

<activity android:name="com.amazon.ags.html5.overlay.GameCircleUserInterface" 
    android:theme="@style/GCOverlay" android:hardwareAccelerated="false"></activity>
<activity
  android:name="com.amazon.identity.auth.device.authorization.AuthorizationActivity"
  android:theme="@android:style/Theme.NoDisplay"
  android:allowTaskReparenting="true"
  android:launchMode="singleTask">
  <intent-filter>
     <action android:name="android.intent.action.VIEW" />
     <category android:name="android.intent.category.DEFAULT" />
     <category android:name="android.intent.category.BROWSABLE" />
     <data android:host="@USER_ACTIVITY_PACKAGE@" android:scheme="amzn" />
  </intent-filter>
</activity>
<activity android:name="com.amazon.ags.html5.overlay.GameCircleAlertUserInterface" 
android:theme="@style/GCAlert" android:hardwareAccelerated="false"></activity>
<receiver
  android:name="com.amazon.identity.auth.device.authorization.PackageIntentReceiver"
  android:enabled="true">
  <intent-filter>
     <action android:name="android.intent.action.PACKAGE_INSTALL" />
     <action android:name="android.intent.action.PACKAGE_ADDED" />
     <data android:scheme="package" />
  </intent-filter>
</receiver>

示例代码

您可以在此处访问示例代码。