> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 适用于 Corona 的 Lua 快速入门

> 在 Windows 或 Mac 上设置 Corona 项目，并使用 PlayFab Corona SDK 客户端库在 Lua 中发起首次 PlayFab API 调用。

本快速入门可协助你在 Corona 引擎中发起首次 PlayFab API 调用。

在调用任何 PlayFab API 之前，你必须拥有一个 [PlayFab 开发者帐户](https://developer.playfab.com)。

## Corona 项目设置

操作系统：本快速入门是针对 Windows 编写的。不过，它也应该能够在 Mac 上正常运行。

1. 下载并安装 Corona：[https://coronalabs.com/](https://coronalabs.com/)。

2. 运行 Corona 并创建一个新项目。如果你尚未完成初次使用步骤，可通过以下链接获取相关信息以帮助你操作：[https://docs.coronalabs.com/guide/start/installWin/index.html](https://docs.coronalabs.com/guide/start/installWin/index.html)

3. 安装、登录并创建新项目后，你应该会看到几个类似下例所示的窗口。

   <img src="https://mintcdn.com/microsoft-4404708b/N3T1ucKV7zIMBudj/images/playfab/sdks/lua/new-project.png?fit=max&auto=format&n=N3T1ucKV7zIMBudj&q=85&s=bdbfa4a84974159ffd7b4b0641f540cb" alt="安装 PlayFab SDK" width="1447" height="926" data-path="images/playfab/sdks/lua/new-project.png" />

4. 在 Corona Marketplace 中激活 PlayFab Client 插件：

   [https://marketplace.coronalabs.com/plugin/playfab-client](https://marketplace.coronalabs.com/plugin/playfab-client)

5. PlayFab 安装完成！

## 设置你的第一个 API 调用

本指南提供了进行首次 PlayFab API 调用所需的最简步骤。确认信息将在 Corona 引擎输出日志中显示。

在你常用的文本编辑器中，将以下几行*添加*到 `build.settings`。

```lua theme={null}
settings =
{
    -- ADD THESE THREE LINES at the top, leave everything else as-is
    plugins = {
        ["plugin.playfab.client"] = { publisherId = "com.playfab" }
    },

-- Other existing lines...
}
```

<Note>
  要查阅本示例中 loginRequest 对象的正确格式，请参阅 [LoginWithCustomID](xref:titleid.playfabapi.com.client.authentication.loginwithcustomid) 的 API 参考。
</Note>

在你常用的文本编辑器中，将 **main.lua** 文件的内容*替换*为以下内容。

```lua theme={null}
local pfClient = require("plugin.playfab.client")
local PlayFabClientApi = pfClient.PlayFabClientApi
PlayFabClientApi.settings.titleId = "144"

local loginRequest = {
    -- See the API reference for LoginWithCustomID.
    CustomId = "GettingStartedGuide",
    CreateAccount = true
}
PlayFabClientApi.LoginWithCustomID(loginRequest,
    function(result) print("Congratulations, you made your first successful API call!") end,
    function(error) print("Something went wrong with your first API call.\nHere's some debug information:\n" .. error.errorMessage) end
)
```

## 完成并执行

Corona 会在你保存时自动立即执行项目源代码。因此，只要你更新并保存这两个文件，就应该看到：

<img src="https://mintcdn.com/microsoft-4404708b/N3T1ucKV7zIMBudj/images/playfab/sdks/lua/finish-and-execute.png?fit=max&auto=format&n=N3T1ucKV7zIMBudj&q=85&s=59fd602abd813dbde3966cc4373877bf" alt="下载 Corona 插件 - 完成并执行" width="1182" height="974" data-path="images/playfab/sdks/lua/finish-and-execute.png" />

此时，你可以开始进行其他 API 调用并构建你的游戏。有关所有可用客户端 API 调用的列表，请参阅我们的 [PlayFab API 参考](/services/playfab/api-references)文档。

祝你编码愉快！

## 代码解析

这个可选的最后一节将逐行介绍上面示例的各个部分。

* build.settings
  * `plugins = {`
    * 这会调用 Corona 插件系统，并告诉它下载并在你的项目中安装 Corona Marketplace 插件
  * `["plugin.playfab.client"] = { publisherId = "com.playfab" }`
    * 这明确告诉它下载 PlayFab 客户端插件。
* main.lua
  * require() 行：
    * 这是进行 PlayFab API 调用所需的最少导入内容。
  * `PlayFabClientApi.settings.titleId = "xxxx"`
    * 每个 PlayFab 开发者都会在 Game Manager 中创建一个 title。发布游戏时，你必须将该 titleId 编入游戏代码中。这可让客户端知道如何访问 PlayFab 中的正确数据。对于大多数用户来说，只需将其视为使 PlayFab 正常工作的必备步骤即可。
  * `local loginRequest = { CustomId = "GettingStartedGuide", CreateAccount = true }`
    * 大多数 PlayFab API 方法都需要输入参数，这些输入参数被打包到一个请求对象中
    * 每个 API 方法都需要一个唯一的请求对象，其中包含可选参数和必需参数的组合
      * 对于 `LoginWithCustomIDRequest`，有一个必需参数 `CustomId`（唯一标识一个玩家）和 `CreateAccount`（允许通过此调用创建新帐户）。
  * `PlayFabClientApi.LoginWithCustomID(loginRequest, {OnLoginSuccess-function}, {OnLoginError-function})`
    * 这将启动对 `LoginWithCustomID` 的异步请求，成功时将调用第一个 (`OnLoginSuccess`) 回调，失败时将调用第二个 (`OnLoginError`) 函数。
  * 对于登录，大多数开发者会希望使用更合适的登录方法。
    * 有关所有登录方法及输入参数的列表，请参阅 [PlayFab 登录文档](xref:titleid.playfabapi.com.client.authentication)。常用选项包括：
      * [LoginWithAndroidDeviceID](xref:titleid.playfabapi.com.client.authentication.loginwithandroiddeviceid)
      * [LoginWithIOSDeviceID](xref:titleid.playfabapi.com.client.authentication.loginwithiosdeviceid)
      * [LoginWithEmailAddress](xref:titleid.playfabapi.com.client.authentication.loginwithemailaddress)
    * `OnLoginSuccess` 是任何接受单个参数 (result) 的函数。
      * result 对象将根据所调用的 API 包含所请求的信息。
      * `LoginResult` 包含有关玩家的一些基本信息，但对大多数用户来说，登录只是调用其他 API 之前的必备步骤。
    * `OnLoginError` 是任何接受单个参数 (error) 的函数。
      * API 调用可能因多种原因失败，你应始终尝试处理失败情况。
      * API 调用失败的原因（按可能性顺序排列）：
        * 未设置 `PlayFabSettings.TitleId`。如果你忘记为你的 title 设置 `titleId`，则任何操作都不会成功。
        * 请求参数。如果你没有为特定 API 调用提供正确或必需的信息，则调用将失败。详情请参阅 `error.errorMessage`、`error.errorDetails` 或 `error.GenerateErrorReport()`。
        * 设备连接问题。手机会不断丢失/恢复连接，因此任何时候的任何 API 调用都可能随机失败，然后立即恢复正常。进入隧道可能会使你完全断开连接。
        * PlayFab 服务器问题。与所有软件一样，可能会出现问题。请参阅我们的[发行说明](/services/playfab/release-notes)了解更新信息。
        * 互联网并非 100% 可靠。有时消息会损坏或无法到达 PlayFab 服务器。
      * 如果你在调试问题时遇到困难，且错误信息中的内容不够详尽，请访问我们的[论坛](https://community.playfab.com/index.html)。


## Related topics

- [Defold 的 Lua 快速入门](/zh-CN/services/playfab/sdks/lua/quickstart-defold.md)
- [适用于 Linux 的 C++ 快速入门](/zh-CN/services/playfab/sdks/playfab-cpp/quickstart-linux.md)
- [适用于 Windows 的 C++ 快速入门](/zh-CN/services/playfab/sdks/playfab-cpp/quickstart-windows.md)
- [适用于 GDK 的 C/C++ 快速入门](/zh-CN/services/playfab/sdks/playfab-cpp/quickstart-gdk.md)
- [快速入门 - 适用于 C# 的 PlayFab 客户端库](/zh-CN/services/playfab/sdks/c-sharp/quickstart.md)