異步事件 · GameMaker Studio 2 幫助文檔

## 異步事件 ![物體編輯器異步事件](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/2_interface/1_editors/events/images/editor_objects_async.png)**異步事件**是當*GameMaker Studio 2*從某些外部源（可以來自 Web 或運行游戲的設備）收到 “回調” 時觸發的事件。你告訴*GameMaker Studio 2*做一些事情，比如加載一個圖像，然后它就會在加載圖像時同時干其它事情。然后，當請求（即加載圖像）完成后，將向*GameMaker Studio 2*發送回調，并且將觸發為該類型的回調定義的**異步事件**。請注意，異步事件將針對具有它們的*所有*實例觸發，就像按鍵事件一樣，因此你可以在一個實例中執行http\_get調用，但在另一個實例中使用異步 HTTP 事件來處理回調。 **注意**：你應該知道，由于瀏覽器中的 XSS 保護，對來自跨域的請求和嘗試加載資源的操作都被阻止，并且在使用以下任何事件時可能會返回空白結果有與異步事件類別相關的各種類型的事件，它們都在以下部分中解釋： **注意：**以下各節中提到的變量async\_load僅在這些事件中有效，因為指向的ds\_map是在**事件開始時創建的**，然后在結尾處再次刪除，此變量在其他時間被重置為 -1。錄音回放此事件只能由[音頻隊列播放函數](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/audio/audio%20buffers.html)觸發，并將返回存儲在變量async\_load中的[ds\_map](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/data_structures/ds%20maps/index.html)，其中包含與觸發事件的音頻隊列相關的不同鍵 / 值對。選擇要回放的音頻隊列并完成該音頻隊列中的緩沖區播放后，將觸發該事件。 ds\_map 中將提供以下鍵： * "**queue\_id**" - 已完成播放的隊列的索引，由函數[audio\_create\_play\_queue](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/audio/audio_create_play_queue.html)返回。 * "**buffer\_id**" - 不再播放的緩沖區的緩沖區 ID * "**queue\_shutdown**" - 在正常播放期間設置為 0，在接收到事件時設置為 1，因為已調用[audio\_free\_play\_queue](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/audio/audio_free_play_queue.html)。如果將其設置為 1，你不希望排隊等待任何進一步的數據。由于可以從多個緩沖區創建音頻隊列，因此當到達緩沖音頻的每個部分的末尾時，可以針對一個隊列多次觸發該事件，因此使用了 “buffer\_id” 鍵。 **注意：**變量async\_load僅在異步事件中有效，因為指向的ds\_map是在事件開始時創建的，然后在結尾處再次刪除，此變量將重置為值 -1。但是，**必須使用適當的函數清除**從事件創建的所有其他數據結構。在下面給出的使用示例中，我們將創建一個音頻隊列，其中添加了 10 個緩沖的音頻聲音，然后播放隊列： audio\_queue = audio\_create\_play\_queue(buffer\_s16, 11052, audio\_mono); for (var i = 0; i < 10; i++;) ???{ ???audio\_queue\_sound(audio\_queue, audio\_buffer\[i\], 0, buffer\_get\_size(audio\_buffer\[i\])); ???} audio\_play\_sound(audio\_queue, 0, true); 現在每個游戲步都會檢測到錄音將觸發異步音頻錄制事件，你可以在此處處理錄制的輸入，如下所示： var queue = async\_load\[?"queue\_id"\]; var num = 0; if queue = audio\_queue ???{ ???for (var i = 0; i < 10; i++;) ??????{ ??????if async\_load\[?"buffer\_id"\] == audio\_buffer\[i\] ?????????{ ?????????buffer\_seek(audio\_buffer\[i\], buffer\_seek\_start, 0); ?????????num = i; ?????????} ??????} ???if num == 9 ??????{ ??????audio\_stop\_sound(audio\_queue); ??????audio\_free\_play\_queue(audio\_queue); ??????} ???} 在這里我們檢查隊列 ID，如果它是我們想要的那個，我們就檢查緩沖區 ID 以查看哪個緩沖已經完成播放。然后，我們還將局部變量設置為該索引值以便稍后檢查，并將緩沖區設置回該聲音的開始。一旦我們的局部變量達到 9，表明隊列已經完成，我們停止播放聲音并釋放隊列。錄音此事件只能由[audio\_start\_recording()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/audio/audio_start_recording.html)函數觸發，并將返回存儲在變量async\_load中的[ds\_map](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/data_structures/ds%20maps/index.html)，其中包含不同的鍵 / 值對，具體取決于觸發事件的函數的回調。 ds\_map 中將提供以下鍵： * "**buffer\_id**" - 可用于檢索音頻數據的臨時緩沖區的 ID * "**channel\_index**" - 由此數據來自的調用函數返回的記錄通道索引 * "**data\_len**" - 你收到的數據長度（以字節為單位） **注意：**如本頁開頭所述，變量async\_load僅在異步事件中有效，因為指向的ds\_map是在事件開始時創建的，然后在結束時再次刪除。但是，請注意，所有音頻與地圖一起存儲的臨時緩沖區也將在事件結束時刪除，因此如果要保留以供以后使用，則應將其復制到自定義緩沖區。在下面的用法示例中，我們將創建一個自定義緩沖區來存儲我們錄制的音頻，并將我們的游戲設置為從輸入源 0 錄制： channel\_index = audio\_start\_recording(0); audio\_buffer = buffer\_create(len, buffer\_fast, 1); 現在每個游戲步都會檢測到錄音將觸發異步音頻錄制事件，你可以在此處處理錄制的輸入，如下所示： var channel = async\_load\[?"channel\_index"\]; if channel == channel\_index ???{ ???len = async\_load\[?"data\_len"\]; ???buffer\_copy(async\_load\[?"buffer\_id"\], 0, len, audio\_buffer, 0); ???} 在這里，我們只需檢查 “channel\_index” 鍵以確保它與我們開始記錄時返回的值匹配，如果是，我們將為此事件創建的臨時緩沖區的內容復制到我們的自定義緩沖區中。之后，你可以使用自定義緩沖區執行所需操作 - 你可以使用專用緩沖區音頻函數播放它，你可以處理它并通過網絡發送它，你可以將其保存到磁盤... 一旦你在緩沖區中有錄制的音頻，你可以做任何你想要的事情。云云事件是由其中一個[cloud\_函數](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/index.html)（如[cloud\_synchronise](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/cloud_synchronise.html)）的回調觸發的事件。它實際上生成了一個獨特的ds\_map，并存儲在特殊變量**async\_load**中（請參閱各個函數以獲取更詳細地解釋此事件使用的代碼示例）。此 ds\_map 具有以下結構： * **"status":**這是狀態碼，其中負值表示錯誤，錯誤詳情包含在 “errorstring” 中。 0 （或者大于 0 的值）代表成功（見下文）的返回, “resultString” 中包含返回的消息數據。 * * **"id":**返回被調用的函數的 id，如果你發送了一系列的cloud\_請求，你需要知道被回應的是哪一個，所以你要用這個值來和發送時存儲的值進行比較來找到你需要的請求。 * * **"description":**上傳的最后一個文件的描述。 * * **"resultString":**從云端返回的二進制數據。 * * **"errorString":**返回的錯誤消息。返回值 "status" 的詳細映射關系如下如下： | 狀態值 | errorString / resultString | 描述 | | --- | --- | --- | | \-1 | errorString = "Not logged in to " | 未能成功登陸到給定的云服務。 | | 0 | resultString = recovered data | 從云端下載新的游戲數據（在 cloud\_synchronise 后調用）。 | | 1 | resultString = "AlreadySynchronized" | 自從上次調用以來 cloud\_synchronise 沒有新的數據。 | | 2 | resultString = "ConflictDeferral" | 遇到沖突,但玩家選擇忽略它。 | | 3 | resultString = "GameUploadSuccess" | 來自[cloud\_string\_save](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/cloud_string_save.html)或[cloud\_file\_save](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/cloud_file_save.html)的數據已成功上傳到云端 | | \-n | errorString = Description of error | 負數意味著同步失敗。 | 對話框與上述事件一樣，**對話框**事件僅在從其中一個特殊異步用戶函數（如[get\_login\_async()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/get_login_async.html)）返回時觸發（請參閱此函數以獲取有關如何使用此事件的擴展代碼示例）。這些事件是要求某種類型的用戶輸入的事件，可以是名稱、登錄詳細信息、數字或顏色等...... 由于大多數設備不喜歡在循環中等待回復，它們必須是異步的，*GameMaker Studio 2*將繼續在后臺運行，而這些函數打開對話框，直到它們獲得觸發此事件的所需用戶輸入。同樣，會返回[ds\_map](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/data_structures/ds%20maps/index.html)，其 id 保存在特殊變量**async\_load**中。此映射中保存的值取決于所使用的功能，有關詳細信息，請參閱本手冊中每個功能的各個條目。 HTTP HTTP 事件是由一個[http\_函數](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/index.html)（如[http\_post\_string](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/http_post_string.html)）的回調觸發的事件。它實際上生成了一個ds\_map（有時稱為“字典”），它獨有于此事件并存儲在特殊變量async\_load中（請參閱各個函數以獲取更詳細地解釋此事件使用的代碼示例）。此ds\_map具有以下結構： * **"id":**從命令返回的id。如果你發出一系列http\_請求，那么你需要知道你得到了哪一個回復，因此你可以使用這個值來比較你最初發送請求時存儲的值，以找到正確的請求。 * * **"status":**為錯誤返回小于 0 的值，為成功返回 0，如果正在下載內容則返回 1。 * * **"result":**收到的數據（僅限字符串），或者如果使用了[http\_get\_file()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/http_get_file.html)，則是下載的文件的路徑。 * * **"url":**你請求的完整網址。 * * **"http\_status":**原始 http 狀態代碼（如果可用）。這將返回大多數瀏覽器的標準 Web 狀態代碼，例如：304 表示 “未修改” 或 204 表示 “無內容” 等... 這適用于使用http\_post\_string()函數時，但每個http\_函數可能會返回略有不同的映射，因此請參閱每個函數的手冊條目，以找出為其返回的精確數據。 **注意：**當async\_load創建[ds\_map](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/data_structures/ds%20maps/index.html)時，這些函數在與[json\_encode](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/file%20handling/json_encode.html)和[json\_decode](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/file%20handling/json_decode.html)函數結合使用時特別有用。如果你已請求下載文件，則此映射還可能提供其他數據。在這種情況下，“status” 的值為 1，ds\_map 將保存這些額外的鍵： * **"contentLength":**這是 Web 服務器所說的你應該接收的文件大小（如果服務器不返回此數據，則可能為 -1）。 * * **"sizeDownloaded":**已下載的數據大小。請注意，*不會*為接收到的每個數據包觸發事件，而是在主游戲循環中的下載過程中隨時更新事件。另請注意，目前此功能僅適用于常規*Windows*目標平臺。應用內購只有在為游戲激活[應用內購](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/in%20app%20purchases/index.html)時才能觸發此事件。如果添加了此功能，則在以下情況下將觸發該事件： * 商店狀態發生變化。 * 一種產品（或多種產品）已被激活。 * 產品和購買已經恢復。 * 已購買產品。 * 產品已被消費。該事件將始終創建一個特殊的[ds\_map](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/data_structures/ds%20maps/index.html)，其索引 ID 存儲在內置變量**iap\_data**中。此映射將*始終*包含鍵 “**type**”，它將包含以下常量值之一： | 常量 | 描述 | | --- | --- | | iap\_ev\_storeload | 在目標平臺存儲中檢測到更改時會觸發此操作。 | | iap\_ev\_product | 激活產品時會觸發此事件，并包含有關產品的其他信息。 | | iap\_ev\_restore | 只有在使用[iap\_restore\_all](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/in%20app%20purchases/iap_restore_all.html)函數時才會觸發此事件。 | | iap\_ev\_purchase | 購買完成后，將觸發此事件。 | | iap\_ev\_consume | 當你使用函數[iap\_consume](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/in%20app%20purchases/iap_consume.html)時，它會觸發此事件。 | 這些可能的事件 “類型” 中的每一個都將為iap\_datads\_map 添加額外的密鑰，然后可以對其進行解析以獲取必要的購買或產品信息。下面列出了每個事件 “類型” 的iap\_data映射的確切內容。 iap\_ev\_storeload 當你激活購買時，你的游戲將嘗試聯系目標商店，在此過程中觸發此事件。然后，iap\_data映射將具有一個附加鍵 “**status**”，它將具有以下常量之一作為其值： | 常量 | 描述 | | --- | --- | | iap\_storeload\_ok | 已連接商店，連接良好。 | | iap\_storeload\_failed | 存在連接錯誤或由于某種原因存儲不可用。 | iap\_ev\_product 所有激活的購買都會觸發此事件 “類型”，但每次購買只會觸發一次，因此如果你已激活十個產品，則應該會觸發此事件十次。如果你收到此事件，則iap\_datads\_map 將保留附加鍵 “**index**”，其中包含正在激活的產品的唯一**產品 ID**字符串。然后，你可以使用函數[iap\_product\_details](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/in%20app%20purchases/iap_product_details.html)以及此產品 ID 來獲取更多信息。 **注意：**Google Play（Android）一次只能請求產品的 20 條詳細信息，這會導致具有大量產品的應用程序的加載時間相當長。 iap\_ev\_restore 當你調用函數[iap\_restore\_all](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/in%20app%20purchases/iap_restore_all.html)時，它將觸發此事件，向iap\_data ds\_map添加 “**result**” 鍵。此鍵將包含true或false，以指示是否已從目標商店成功還原購買數據。 iap\_ev\_purchase 在使用函數[iap\_acquire](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/in%20app%20purchases/iap_acquire.html)請求購買時，將觸發此事件類型。iap\_datads\_map 將具有附加鍵 “**index**”，其中包含所購買產品的唯一**購買 ID**值。然后，你可以使用函數[iap\_purchase\_details](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/in%20app%20purchases/iap_purchase_details.html)以及此購買 ID 來獲取更多信息。 **注意：**如果購買的產品是消耗品，則**必須先使用**iap\_consume進行購買，然后才能進一步購買。 iap\_ev\_consume 使用函數[iap\_consume](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/in%20app%20purchases/iap_consume.html)時，將觸發此事件類型。iap\_datads\_map 將具有附加密鑰 “**product**”，其中包含正在使用的產品的唯一**產品 ID**字符串。加載圖片只要你使用了具有適用加載文件功能的有效 URL 或路徑，就會在將圖像加載到*GameMaker Studio 2*時觸發此事件。例如，假設你要加載精靈圖像，并且僅在加載時將實例的當前精靈更改為新精靈。那么你會在創建事件或計時器事件中有這樣的事情（例如）： spr = sprite\_add("http://www.angusgames.com/game/background1.png", 0, false, false, 0, 0); 現在，這將開始將圖像加載到設備或瀏覽器中，但在等待加載文件時*不會*阻止*GameMaker Studio 2*。相反，*GameMaker Studio 2*將繼續正常運行，直到加載圖像并且回調觸發**加載圖片**事件，其中創建[ds\_map](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/data_structures/ds%20maps/index.html)并將其存儲在特殊變量**async\_load**中。該映射包含以下信息： * **"filename":**你請求的文件的完整路徑。 * * **"id":**已加載資源的 ID。這與你為其分配資源的變量相同。 * * **"status":**為錯誤返回小于 0 的值。然后，你將在此事件中將新加載的圖像分配給背景。對于精靈和聲音也是如此，如上所示為每個資源生成 ds\_map，以下代碼示例演示了如何在此事件中使用返回的信息： if ds\_map\_find\_value(async\_load, "id") == spr ???{ ???if ds\_map\_find\_value(async\_load, "status") >= 0 ??????{ ??????sprite\_index = spr ??????} ???} 上面的代碼將首先檢查已創建的 ds\_map 的 id，然后檢查回調的狀態。如果該值大于或等于 0（信號成功），則回調的結果將用于將背景索引設置為新加載的圖像。聯網網絡事件是由任何傳入網絡流量觸發的事件，并鏈接到[網絡函數](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/networking/index.html)。此事件生成一個特殊的[ds\_map](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/data_structures/ds%20maps/index.html)，該事件專用于此事件，并存儲在特殊變量**async\_load**中。此ds\_map將包含不同的信息，具體取決于生成它的網絡事件的類型。常見網絡事件以下鍵對所有接收的網絡功能都是通用的，并且始終存在于async\_load映射中： * **"type":**這將使下面列出的常量之一作為其返回值，并指定網絡事件類型。 * * **"id":**正在接收事件的套接字 id（由[network\_create\_server](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/networking/network_create_server.html)或[network\_create\_socket](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/networking/network_create_socket.html)函數返回的實數）。在大多數情況下，返回的套接字 ID 是觸發事件的 TCP 或 UDP 套接字的 ID，但是如果在*服務器*中觸發事件并且它是數據事件（見下文），那么套接字 ID 是發送數據的*客戶端*套接字 ID。 * * **"ip":**套接字的 IP 地址（作為字符串）。 * * **"port":**與 IP 地址關聯的端口（在使用 UDP 時很有用）。 “type” 鍵的可能返回值可以是下面列出的四個常量中的任何一個： | 常量 | 描述 | | --- | --- | | network\_type\_connect | 事件由連接觸發。 | | network\_type\_disconnect | 事件由斷開連接觸發。 | | network\_type\_data | 事件由傳入數據觸發。 | | network\_type\_non\_blocking\_connect | 事件由配置為非阻塞的連接觸發（你可以使用函數[network\_set\_config()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/networking/network_set_config.html)）。 | 連接 / 斷開連接如果你有類型為network\_type\_connect、network\_type\_non\_blocking\_connect或network\_type\_disconnect的事件，則async\_load映射將具有以下附加鍵： * **"socket":**此鍵將保持連接 / 斷開套接字 ID。 * * **"succeeded":**此鍵將為 0 或 1，其中 0 表示連接超時，1 表示成功，套接字可以使用。值得注意的是，當*服務器*斷開連接時，網絡事件不會在*客戶端*中觸發，并且當連接的服務器斷開連接時，即使連接基于 TCP，也不會在客戶端中觸發network\_type\_\*事件。接收數據當你有network\_type\_data類型事件（表示你的網絡已收到數據）時，創建的映射將具有以下鍵： * **"buffer":**這是由事件生成的唯一 “緩沖區 ID”。創建一個 “增長” 類型緩沖區，字節對齊為 1，以保存 id 應存儲在變量中，并用于***此事件中***對緩沖區的所有進一步函數調用。就像async\_load映射一樣，創建的緩沖區會在此事件結束時自動從內存中刪除。有關緩沖區的更多信息，請參閱[參考 - 緩沖區](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/buffers/index.html) * * **"size":**這是正在接收的緩沖區數據的大小（以字節為單位）。 **注意：**創建的緩沖區**僅在這些事件中有效**，并在事件結束時釋放。推送通知推送通知事件是由設備操作系統上的**推送通知**回調觸發的事件，可以是使用函數[push\_local\_notification](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/push_local_notification.html)的本地源，也可以是遠程源（即：你的服務器）。它生成一個獨特于此事件的ds\_map，并存儲在特殊變量**async\_load**中（請參閱觸發異步事件的各個函數，以獲取更詳細地解釋此事件使用的代碼示例）。此ds\_map具有以下鍵： * **"type":**值可以是設備本地通知的 “local”，遠程通知的 “reomte” 或遠程通知注冊的 “register”。 * **"status":**成功的值為 “1”，錯誤的值為 “0”。根據返回的 “類型” 和 “狀態” 值，可能存在其他鍵條目。對于 “status”，如果返回錯誤（“0”），那么你還將擁有以下鍵： * **"error":**包含收到的錯誤的詳細信息。如果 “status” 值為 1（即：無錯誤），則ds\_map將包含以下附加值，具體取決于 “type” 鍵的值： * **"reg\_id":**如果收到的 “type” 是 “register”，則該鍵將保存設備注冊 ID 以進行遠程通知。 * **"data":**如果收到的 “type” 是 “local” 或 “remote”，則此鍵將保存你在調用通知函數時定義的字符串有效內容。為了更好地理解這一點，我們在下面創建了一個小示例代碼段供你查看。在這個示例中,我們將使用下面的代碼來發送一個本地推送通知： var fireTime = date\_inc\_day(date\_current\_datetime(), 1); var data = "daily\_reward"; push\_local\_notification(fireTime, "Ahoy!", "Catch The Haggis Has A Present", data); 設置一個計時器在一天后向設備 “推送” 一個通知。一天以后，無論你的程序是在后臺還是未啟動狀態，玩家都將收到之前設置的通知（在 iOS 平臺標題被游戲的名字替代），然后一個異步的推送通知事件（Push Notification Event）會被觸發。需要注意的是，如果推送時程序運行在前臺，通知將*不會*被展示，但是異步推送事件**仍會觸發**。在事件本身你會這樣處理回調： var type = ds\_map\_find\_value(async\_load, "type"); var status = ds\_map\_find\_value(async\_load, "status"); if status == 0 ???{ ???//error of some kind ???var error = ds\_map\_find\_value(async\_load, "error"); ???show\_debug\_message("error=" + string(error)); ???} else ???{ ???if type == "register" ??????{ ??????global.reg\_id = ds\_map\_find\_value(async\_load, "reg\_id"); ??????} ???else ??????{ ??????var data = ds\_map\_find\_value(async\_load, "data"); ?????????if data == "daily\_reward" ?????????{ ?????????global.Gold += 1000; ?????????} ??????} ???} 保存 / 載入此事件將由與加載和保存文件緩沖區以及從內存加載或卸載音頻時相關的某些函數觸發。事件本身將包含內置的async\_loadDS 映射，該映射將由特定函數所需的密鑰填充。這些列在下面的部分中。緩沖區使用函數[buffer\_save\_async()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/buffers/buffer_save_async.html)或[buffer\_load\_async()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/buffers/buffer_load_async.html)時，將在數據傳輸完成時觸發異步事件。此事件將使用以下鍵 / 值對填充async\_load映射 * **"id":**由所使用的函數返回的異步函數的 ID。 * **"status":**如果正確保存/加載數據，則返回true，否則返回false。這允許你輪詢保存 / 加載進度并顯示消息或更改房間等...當過程完成時。音頻組使用[音頻組](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/audio/audio%20groups.html)時，你可以使用[audio\_group\_load()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/audio/audio_group_load.html)和[audio\_group\_unload()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/audio/audio_group_unload.html)函數加載它們并從內存中卸載它們。使用加載功能時，當為該組設置的完整音頻文件集已加載到內存中時，它將觸發此事件，并使用以下鍵 / 值對填充映射： * **"type":**這告訴我們被調用的事件的類型，并且將是 “audiogroup\_load” 來加載音頻。 * **"group\_id":**將返回已加載的音頻組的 ID（如[音頻組編輯器](c:/source/yoyostudio/documentation/english/2_interface/3_settings/audio.html)中所定義）。當為一個組加載所有音頻時，此事件將觸發，然后可用于更改房間，或播放音樂曲目等... 社交此事件只能由各種特定的[社交函數](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/index.html)觸發，并將返回存儲在變量[async\_load](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/data_structures/ds%20maps/index.html)中的ds\_map，其中包含不同的鍵 / 值對，具體取決于觸發事件的函數的回調。 ds\_map 將包含許多鍵，其中最重要的是 “*id*” 鍵。這將返回一個**常量**，然后可以在代碼中檢查該常量以確定事件已收到的許多回調中的哪一個。解析此密鑰并將返回的值與可用常量進行比較后，你可以繼續從映射中提取其余信息。成就和排行榜函數頁面[社交游戲 - 成就和排行榜](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/achievements%20and%20leaderboards/index.html)參考部分中詳細介紹了函數和回調以及用于觸發此事件的常量，但是在某些情況下，如果沒有來自游戲的函數調用，它將在運行時被觸發： * 從操作系統常用工具欄啟動游戲時 * 當你完成挑戰時 * 當另一位玩家完成挑戰時 * 從操作系統常用工具欄啟動游戲時選擇挑戰任何上述回調都將觸發**社交事件（Social Event）**，并且將生成帶有以下詳細信息的async\_load映射（請注意，有一個不同的 “id” 鍵值來定義調用該事件的每個不同原因，但所有其他內容映射是一樣的）： * "**id**" - 此鍵的值取決于觸發事件的回調類型。它可以是以下常量之一： * **achievement\_challenge\_received**\- 已收到挑戰 * **achievement\_challenge\_completed**\- 挑戰已經完成。 * **achievement\_challenge\_completed\_by\_remote**\- 其他玩家已完成挑戰。 * **achievement\_challenge\_launched**\- 游戲是從具有給定挑戰的操作常用工具欄啟動的。 * "**playerid**" - 挑戰的玩家 id。 * "**issuerid**" - 發出挑戰的人的 id。 * "**state**" - 挑戰的狀態，對于*無效*、*待定*、*已完成*或*已拒絕*，其值為 0 - 3（作為字符串）。 * "**message**" - 挑戰的消息。 * "**issueddate**" - 挑戰的發布日期 * "**completeddate**" - 挑戰的完成日期。 * "**type**" - 給出的挑戰類型。可以是兩個常量之一： * **achievement\_type\_score\_challenge**\- 基于分數值的挑戰。 * **achievement\_type\_achievement\_challenge**\- 基于成就的挑戰。 * "**identifier**" - 挑戰的識別字符串。 * "**score**" - 分數與挑戰是一致的。你可以在下面找到一小段代碼作為使用示例： var ident = ds\_map\_find\_value(async\_load, "id" ); if ident == achievement\_challenge\_completed; ???{ ???player\_id = ds\_map\_find\_value(async\_load, "playerid"); ???issuer\_id = ds\_map\_find\_value(async\_load, "issuerid"); ???state = ds\_map\_find\_value(async\_load, "state"); ???date\_completed = ds\_map\_find\_value(async\_load, "completeddate"); ???date\_issued = ds\_map\_find\_value(async\_load, "issueddate"); ???ach\_type = ds\_map\_find\_value(async\_load, "type"); ???ach\_ident = ds\_map\_find\_value(async\_load, "identifier"); ???ach\_score = ds\_map\_find\_value(async\_load, "score"); ???} Facebook 一些[Facebook 函數](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/asynchronous%20functions/facebook/index.html)將觸發社交異步事件并創建帶有一些特定信息的ds\_map。返回的信息將取決于已調用事件的 “類型”。你可以通過讀取 ds\_map 中的 “type” 鍵來檢查這一點，這將是以下 Facebook 事件的字符串： * "**facebook\_permission\_request**" 當事件被觸發并且屬于這種類型時，還會有其他可以檢查的鍵： * "**requestId**" - 觸發事件的facebook\_request\_xxx\_permission()函數返回的請求 ID 值 * "**result**" - 這將是以下字符串之一： * "**granted**" – 用戶接受了許可 * "**denied**" – 用戶不接受一個或多個權限 * "**error**" – 發生錯誤 * **"error**" - 這將包含錯誤的描述，但*僅*在 “**result**” = “**error**”時出現。 Steam 此事件只能由[Steam API](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/steam%20api/index.html)函數觸發，并將返回存儲在變量async\_load中的[ds\_map](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/data_structures/ds%20maps/index.html)，其中包含不同的鍵 / 值對，具體取決于觸發事件的函數的回調。映射將始終包含鍵 “**event\_type**”，然后可以對其進行解析以查找觸發事件的函數類型并更改所需的代碼。當調用任何觸發此事件的函數時，它將生成一個唯一的異步 ID 值，該值應存儲在變量中并進行檢查，因為async\_load映射將始終包含一個 ID 密鑰，然后你可以解析該密鑰并確保你正在響應正確的事件。實際上，無論用于生成異步響應的 Steam 函數如何，映射都將*始終*包含以下鍵： * "**id**" - 觸發事件的函數返回的異步 ID * * "**result**" - 操作的結果（實際值）。這將是 GML 常量ugc\_result\_success或其他一些實數。因此，你應檢查此常量以確保調用成功，否則某些內容無法正常工作。返回的其余可能值顯示為 Steam “EResult” 值的結果，你應該在 SDK 頭文件steamclientpublic.h中看到所有 89 個可能值。 * * "**event\_type**" - 表示事件類型的字符串（詳見下文）上傳數據使用 Steam 函數上傳排行榜（[steam\_upload\_score()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/steam%20api/steam_upload_score.html)或[steam\_upload\_score\_buffer()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/steam%20api/steam_upload_score_buffer.html)）時，返回的ds\_map將具有以下鍵 / 值對： * "**event\_type**" - 此鍵將保存 “**leaderboard\_upload**” 值 * * "**post\_id**" - 此鍵應與上傳調用函數返回的 ID 值匹配 * * "**lb\_name**" - 此鍵包含已發布到的排行榜的名稱 * * "**success**" - 如果傳輸成功，則為 1，0 為失敗 * * "**updated**" - 如果排行榜得分實際更新（即：新得分更高），則為 1，否則為 0 * * "**score**" - 此鍵保留已發布的分數你可以在分數上傳功能的頁面上查看此示例。下載排行榜使用 Steam 函數下載排行榜（[steam\_download\_scores()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/steam%20api/steam_download_scores.html)、[steam\_download\_scores\_around\_user()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/steam%20api/steam_download_scores_around_user.html)或[steam\_download\_friends\_scores()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/steam%20api/steam_download_friends_scores.html)）時，返回的ds\_map將具有以下鍵 / 值對： * "**event\_type**" - 此鍵將保存 “**leaderboard\_download**” 值 * * "**id**" - 此鍵應與下載調用函數返回的 ID 值匹配 * * "**status**" - 回調的狀態，其中 -1 等于失敗或沒有返回結果，0 等于成功。 * "**lb\_name**" - 此鍵包含已發布到的排行榜的名稱 * * "**numEntries**" - 要返回的排行榜數據的 “行” 數。 * * "**entries**" - 包含另一個 ds\_map 的 JSON 對象字符串，它將包含鍵 “default”（表示其中未包含任何結果）或鍵 “entries”（你可以獲取其值）。 “entries” 的返回值將是包含排行榜中每個排名的[ds\_list](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/data_structures/ds%20lists/index.html)，其中列表中的每個條目本身將引用另一個ds\_map，其中包含鍵 “name”、“score” 和 “rank”，以及它也可能包含 “數據” 鍵，具體取決于用于上載的功能。我們將通過請求給定排行榜的前十名排名并在**Steam 異步事件**中解析其結果來顯示下載得分數據如何工作的示例（有關上傳示例，請參閱相應的功能頁面）。首先，我們需要使用以下代碼請求分數： score\_get = steam\_download\_scores("Game Scores", 1, 10); 這將向 Steam 服務器發送請求，以獲取排行榜 “Game Scores” 中的分數，并將請求的**異步 ID**存儲在變量 “score\_get” 中。然后，將通過以下方式在**Steam 異步事件**中處理： var async\_id = ds\_map\_find\_value(async\_load, "id"); if async\_id == score\_get ???{ ???var entries = ds\_map\_find\_value(async\_load, "entries"); ???var map = json\_decode(entries); ???if ds\_map\_exists(map, "default") ??????{ ??????ds\_map\_destroy(map); ??????exit; ??????} ???else ??????{ ??????var list = ds\_map\_find\_value(map, "entries"); ??????var len = ds\_list\_size(list); ??????var entry; ??????for(var i = 0; i < len; i++;) ?????????{ ?????????entry = ds\_list\_find\_value(list, i ); ?????????steam\_name\[i\] = ds\_map\_find\_value(entry, "name"); ?????????steam\_score\[i\] = ds\_map\_find\_value(entry, "score"); ?????????steam\_rank\[i\] = ds\_map\_find\_value(entry, "rank"); ?????????if (ds\_map\_exists(entry, "data")) ????????????{ ????????????var data = ds\_map\_find\_value(entry, "data"); ????????????var buffId = buffer\_base64\_decode(data); ????????????var message = buffer\_read(buffId, buffer\_string); ????????????show\_debug\_message( " -- attached message: " + string(message)); ????????????buffer\_delete(buffId); ????????????} ?????????ds\_map\_destroy(entry); ?????????} ??????ds\_list\_destroy(list) ??????} ???ds\_map\_destroy(map) ???} 我們在這里做的是首先檢查特殊async\_load映射的 “id” 鍵。如果此值與原始回調函數的值（存儲在 “score\_get” 變量中）相同，則我們將繼續處理數據。我們要做的第一件事就是為關鍵 “entries” 解析async\_loadds\_map，它將包含一個包含排行榜數據的 JSON 對象。然后將此 JSON 對象解碼（請參閱[json\_decode](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/file%20handling/json_decode.html)）作為另一個 ds\_map，并將此新映射 ID 存儲在變量 “map” 中。檢查該映射是否有為 “default” 的鍵，如果有的話，則銷毀該映射并退出該事件。如果未找到 “default” 鍵，則代碼將解析映射以提取有關排行榜的必要信息，方法是首先從 ds\_map 的 “entries” 鍵中提取 ds\_list，然后循環遍歷列表的每個條目以獲取*另一個*ds\_map，其中包含每個條目的名稱，分數和排名。然后將這些值存儲在數組中，然后檢查是否有其他 “數據” 鍵。如果有（即：分數是使用附加數據包上傳的），那么我們也會解析它并將其發送到編譯器控制臺進行調試，然后再銷毀緩沖區然后繼續銷毀映射。請注意，如果包含 “data” 鍵，則需要先使用[buffer\_base64\_decode()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/buffers/buffer_base64_decode.html)對其進行解碼，然后才能正確讀取。一旦循環完成，條目列表就會像從其獲取的映射一樣被銷毀。無需銷毀async\_loadds\_map，因為這是由*GameMaker Studio 2*為你處理的。下載 UGC（用戶生成的內容）使用 Steam 功能下載[用戶生成內容（UGC）](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/steam%20api/user%20generated%20content/index.html)時，其中一些將觸發此事件。但是，每個函數都會生成一個具有不同鍵 / 值對的async\_loadds\_map（盡管它們通常將始終包含 “**id**”、“**result**” 和 “**event\_type**” 鍵），因此，請參閱特定于所使用的函數的頁面，以獲得詳細信息和示例。獨特的 UGC 事件當用戶訂閱游戲外的項目時，也可以觸發 Steam 異步事件 - 例如，他們選擇跳轉到瀏覽器并訂閱新項目然后選項回到游戲。在這些情況下，async\_load映射將**僅**包含以下詳細信息（并且沒有列出本頁頂部的默認值）： * "**event\_type**" - 此鍵將保存 “**ugc\_item\_installed**” 值 * * "**published\_file\_id**" - 新安裝的 UGC 項的 ID（你可以使用函數[steam\_ugc\_get\_item\_install\_info()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/steam%20api/user%20generated%20content/steam_ugc_get_item_install_info.html)來獲取已安裝項的路徑） * 訂閱創意工坊項目時也可以觸發 Steam 異步事件 - 從應用程序內部或從創意工坊瀏覽器外部 - 并且在這些情況下，async\_load映射將包含以下鍵 / 值對： * "**event\_type**" - 此鍵將保存 “**ugc\_item\_subscribed**” 值 * * "**published\_file\_id**" : 此密鑰具有新訂閱項的已發布文件ID * 如果任何項目也未被訂閱，則會觸發該事件，數據結構映射包含以下內容： * "**event\_type**" - 此鍵將保存 “**ugc\_item\_unsubscribed**” 值 * * "**published\_file\_id**" : 此密鑰具有未訂閱項的已發布文件 ID * 系統此事件只能由系統級事件觸發（例如檢測到游戲手柄或自動登錄到 XBox Live），它將返回存儲在變量async\_load中的[ds\_map](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/data_structures/ds%20maps/index.html)，其中包含不同的鍵 / 值對，具體取決于系統觸發回調的事件級別。游戲手柄當連接或斷開游戲手柄觸發此事件時，它將返回async\_load映射中的以下鍵 / 值對之一： * "**event\_type**" - 收到的系統事件的類型，它將是以下字符串之一： * "**gamepad discovered**" - 當系統報告已連接新游戲手柄時發生 * "**gamepad lost**" - 當系統失去與游戲手柄的連接時發生 * "**pad\_index**" - 已添加或刪除的游戲手柄的索引此事件現在允許你將所有游戲手柄檢查邏輯從步驟事件或警報事件移動到系統事件中，并僅在實際需要時運行它。虛擬鍵盤當為打開或關閉的虛擬鍵盤觸發此事件時，它將在async\_load映射中返回以下鍵 / 值對： * "**event\_type**" - 收到的系統事件的類型，它將是虛擬鍵盤的 “**虛擬鍵盤狀態**”。 * * "**虛擬鍵盤高度**" - 虛擬鍵盤的高度（以像素為單位）。如果鍵盤不可見，則該值為 0。 * * "**鍵盤狀態**" - 鍵盤的當前狀態，作為以下字符串之一返回： * "正在執行隱藏動作" * "隱藏" * "正在執行顯示動作" * "可見" 有關虛擬鍵盤的更多信息，請參閱[此處](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/controls/virtual%20keys/index.html)。 XBox Live 在以**XBox One**為目標平臺并使用**UWP**導出時，如果勾選[UWP 游戲選項](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/2_interface/3_settings/game_options/options_windowsuwp.html)中的**啟用 XBox Live**選項，可以觸發異步系統事件。當你啟動啟用了 Xbox Live 的*GameMaker Studio 2*UWP 項目時，項目將自動嘗試以靜默方式登錄 Xbox Live。此登錄嘗試的結果將作為async\_load映射中的以下鍵 / 值對之一返回： * "**event\_type**" - 收到的系統事件的類型，它將是以下字符串之一： * "**user signed in**" - 靜默用戶登錄已成功完成 * "**user sign in failed**" - 靜默用戶登錄失敗（當發生這種情況時，你可以使用函數[xboxlive\_show\_account\_picker()](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/xbox_live/xboxlive_show_account_picker.html)讓用戶選擇要登錄的帳戶） * "**user signed out**" - 用戶已退出有關 XBox Live 可用特定函數的更多信息，請參閱[此處](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/xbox_live/index.html)。 Audio System Status This event type is specifically for use when working with the HTML5 target, as it will be triggered every time the Web Audio context status changes. This means that if you have, for example, a piece of looping background music, then you can pause it or stop and restart it, based on this event triggering. This can be checked by looking for the following key/value pair in theasync\_loadmap: * "**event\_type**" - the type of system event received, which will be the following string for an audio event: * "**audio\_system\_status**" - The audio system has initialised or the context has changed. If this event type is triggered, then there will be an additional key in theasync\_loadmap: * "**status**" - The status of the audio system, which will be one of the following two strings * "**available**" - The audio system is initialised and available to play sounds * "**unavailable**" - The audio system is not initialised, or the context is not currently running, and so can't play sounds (all sound playing functions will return -1) For more information on the specific functions available for Audio, please see[here](https://gamemakerchina.github.io/GMS2_manual_en2ch/source/_build/3_scripting/4_gml_reference/audio/index.html). **NOTE**: While this event is designed for use with the HTML5 target, it will also be triggered on*all*other platforms, but on everything (except HTML5) it will only be triggered once on Game Start when the audio engine is first initialised.