> ## 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 開發人員帳戶](https://developer.playfab.com)，才能呼叫任何 PlayFab API。

## 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 Engine 輸出記錄中看到確認訊息。

在您慣用的文字編輯器中，將下列幾行*新增*至 `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 參考](/zh-TW/services/playfab/api-references)文件。

祝您程式撰寫愉快！

## 解構程式碼

這個選擇性的最後一節會逐行說明上述範例的每個部分。

* build.settings
  * `plugins = {`
    * 這會叫用 Corona 外掛程式系統，並指示它在您的專案中下載並安裝 Corona Marketplace 外掛程式
  * `["plugin.playfab.client"] = { publisherId = "com.playfab" }`
    * 這會指示它特別下載 PlayFab Client 外掛程式。
* main.lua
  * require() 這幾行：
    * 這是進行 PlayFab API 呼叫所需的最少匯入項目。
  * `PlayFabClientApi.settings.titleId = "xxxx"`
    * 每位 PlayFab 開發人員都會在 Game Manager 中建立遊戲。當您發佈遊戲時，必須將該 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`。如果您忘記將 `titleId` 設定為您的遊戲，則一切都無法運作。
        * 要求參數。如果您沒有為特定 API 呼叫提供正確或必要的資訊，呼叫就會失敗。如需詳細資訊，請參閱 `error.errorMessage`、`error.errorDetails` 或 `error.GenerateErrorReport()`。
        * 裝置連線問題。行動電話會不斷失去/恢復連線，因此任何 API 呼叫都可能隨時隨機失敗，然後又立即恢復正常。進入隧道可能會讓您完全中斷連線。
        * PlayFab 伺服器問題。就像所有軟體一樣，可能會發生問題。如需更新資訊，請參閱我們的[版本資訊](/zh-TW/services/playfab/release-notes)。
        * 網際網路並非 100% 可靠。有時訊息會損毀或無法送達 PlayFab 伺服器。
      * 如果您在偵錯問題時遇到困難，而錯誤資訊中的內容又不足夠，請造訪我們的[論壇](https://community.playfab.com/index.html)。


## Related topics

- [Defold 的 Lua 快速入門](/zh-TW/services/playfab/sdks/lua/quickstart-defold.md)
- [Unity 快速入門](/zh-TW/services/playfab/sdks/unity3d/quickstart.md)
- [適用於 Linux 的 C++ 快速入門](/zh-TW/services/playfab/sdks/playfab-cpp/quickstart-linux.md)
- [適用於 Windows 的 C++ 快速入門](/zh-TW/services/playfab/sdks/playfab-cpp/quickstart-windows.md)
- [Unreal Engine 快速入門](/zh-TW/services/playfab/sdks/unreal/quickstart.md)