Partner Center 設定
為您的遊戲啟用 XBOX services 與 Game Saves
若要使用 Game Saves API，請在 Partner Center 中完成下列步驟。- 啟用 XBOX services。
- 登入 Partner Center。
- 前往您的遊戲，然後在設定中啟用 XBOX services。如需此步驟的詳細資訊，請參閱在 Partner Center 設定應用程式或遊戲 (適用於受管理的合作夥伴)。
- 取得您的服務設定識別碼 (SCID)。所有讀取與寫入作業都必須與 SCID 相關聯。SCID 也用於 Game Saves 初始化。
- 在 Partner Center 中，於遊戲的 XBOX services > XBOX settings 索引標籤下找到 SCID。您也可以在此頁面上找到您的 Microsoft 帳戶 (MSA) 應用程式識別碼 (MSAAppID)。
- 在 Partner Center 中，於遊戲的 XBOX services > XBOX settings 索引標籤下找到 SCID。您也可以在此頁面上找到您的 Microsoft 帳戶 (MSA) 應用程式識別碼 (MSAAppID)。
開發案例
我應該在程式碼的哪裡整合 Game Saves？
Game Saves 邏輯取決於使用者登入。請將 Game Saves 程式碼加在使用者登入流程旁邊。如何確保我的遊戲存檔資料不會損毀？
若要安全地儲存資料並避免損毀，請遵循下列步驟。此指引適用於所有存檔作業。- 寫入暫存檔案。
- 將存檔資料序列化到新檔案 (例如
save.tmp)，而不是覆寫目前使用中的存檔。此步驟可在處理程序於寫入途中遭到中斷時，保護現有的存檔。
- 將存檔資料序列化到新檔案 (例如
- 在寫入完全認可到磁碟之後，關閉寫入控制代碼。
- 使用 Win32 ReplaceFile，以不可部分完成的方式將舊存檔檔案取代為新的暫存檔案。
如何支援離線裝置？
您必須負責決定在初始化 Game Saves 之前與之後發生連線中斷時，遊戲的行為方式。 如需離線行為的詳細資訊，請參閱了解 Game Saves 同步流程。我需要注意哪些使用者互動？
當動作需要使用者輸入時，作業系統會顯示系統提示。如需這些提示的資訊，請參閱 Game Saves 對話方塊。是否有方法可以只在本機與裝置上儲存？
如果您將null 使用者控制代碼傳遞給 Game Save 初始化程序，系統會建立僅限機器的提供者。資料會儲存在本機並保留在裝置上，上限為 256 MB。資料不會同步到雲端。
如需 Game Saves 儲存空間的詳細資訊，請參閱 Game Saves 儲存系統。
透過裝置管理遊戲存檔
使用檔案總管存取 PC 上的本機遊戲存檔
如果您的遊戲在 PC 上執行，您可以直接存取檔案。視 Game Saves API 的實作而定，您可以在下列位置存取本機遊戲存檔。
當您在 PC 上操作資料時，同步邏輯仍然適用。例如，在遊戲沒有鎖定時修改資料會造成衝突。
存取主機上的本機遊戲存檔
透過 XBOX UI 管理主機存檔資料。請使用下列步驟存取。- 選取 XBOX 控制器上的首頁按鈕。
- 選取 我的遊戲和應用程式 > 查看全部。
- 將游標停留在您的遊戲上，然後選取檢視按鈕。
- 選取已儲存的資料。
- 使用系統 UI 刪除主機上的資料並不會移除儲存在雲端的複本。再次啟動遊戲時，遊戲會從雲端同步資料。
- 機器提供者資料會顯示為沒有名稱的使用者。此資料會保留在裝置上，不會同步到雲端，且繫結到裝置。
測試案例
建立測試案例時，請將資料驗證與遊戲存檔邏輯分開。測試遊戲存檔是否正確地與雲端同步
使用下列步驟測試同步是否正確。測試流程會驗證行為。XGameSaveFiles：
- 確認 SCID 正確。
- 確認您使用的是正確的使用者控制代碼。
- 確認遊戲在目前的遊戲工作階段期間呼叫
XGameSaveFilesGetFolderWithUIAsync。如果遊戲從暫停狀態繼續，請呼叫此函式。- 使用 Fiddler 確認已取得鎖定。
- 儲存此路徑，稍後用來確認資料正在上傳。
- 將一些資料寫入
XGameSaveFilesGetFolderWithUIAsync提供的檔案路徑。 - 終止或暫停遊戲。
- 等待 10 到 30 秒，讓作業系統自動將資料上傳到雲端並釋放鎖定。
- 使用 Fiddler 確認資料已上傳且鎖定已釋放。
- 手動刪除
XGameSaveFilesGetFolderWithUIAsync提供之資料夾中的資料。- 在主機上，透過玩家設定存取此資料。
- 再次啟動遊戲，然後嘗試讓使用者登入。
- 會出現同步對話方塊，顯示正在從雲端進行下載同步。
測試遊戲存檔是否正確漫遊
如需確認資料是否漫遊的測試計畫，請參閱 XR-052-06 測試計畫。移轉案例
在遊戲之間共用遊戲存檔
若要從一個遊戲將資料轉移到另一個遊戲或存取其資料，請完成兩個步驟。- 在 Partner Center 中修改您要存取之遊戲的存取原則。
- 在原始程式碼中為兩個遊戲初始化 Game Saves 提供者。
修改存取原則
遊戲會透過設定存取原則，控制哪些遊戲可以存取其遊戲存檔資料。- 前往 Partner Center。
- 選取 Apps and games > <您的遊戲> > Gameplay settings。
- 在 Gameplay Settings 中選取 Access Policies，然後展開 Connected Storage。
- 選取 Add app/service，然後新增您要提供存取權的遊戲。
- 新增完遊戲後，選取 Save，然後選取 Publish。變更會在一小時內生效。
初始化 Game Save 提供者
現在您已獲得存取第一個遊戲的權限，可以從另一個遊戲讀取XGameSave 資料。
- 如果您使用
XGameSave，請為每個遊戲呼叫XGameSaveInitializeProvider或XGameSaveInitializeProviderAsync。 - 如果您使用
XGameSaveFiles，提供者會隱含地初始化。請為每個遊戲呼叫XGameSaveFilesGetFolderWithUiAsync。
XGameSave 與 XGameSaveFiles 之間的互通性
遊戲可能需要同時使用XGameSave 與 XGameSaveFiles。常見原因可能如下：
- 發行者在主機上已有使用
XGameSave的現有遊戲。 - 發行者不想將該現有遊戲更新為使用
XGameSaveFiles。 - 發行者認為將
XGameSaveFiles新增至 PC 遊戲比使用XGameSave容易，但仍希望支援 PC、主機與 XBOX 遊戲串流之間的跨平台存檔。
XGameSave 與 XGameSaveFiles 之間移動相當簡單。當遊戲呼叫 XGameSaveFilesGetFolderWithUiAsync 時，會使用下列規則將容器與 Blob 對應到目錄與檔案：
- 容器名稱中的任何正斜線 (/) 都會建立檔案所在的目錄結構。
- 下列字元對
XGameSaveFiles而言無效。如果系統遇到這些字元，會將其對應為底線 (_)：- 從 \0 到 \001f (含) 的字元。
- 下列字元對
XGameSaveFiles而言無效。如果系統遇到這些字元，會將其對應為句點 (.)：- 引號 (”)
- 小於符號 (<)
- 大於符號 (>)
- 管道符號 (|)
- 星號 (*)
- 問號 (?)
- 反斜線 (\)
- Blob 名稱中的斜線 (/) 會對應為檔案名稱中的句點 (.)。
- 檔案上限為 16 MB。
XGameSave支援的上傳大小上限為 16 MB。
XGameSaveFiles 移回 XGameSave 時，如果檔案名稱保持不變或未移動，就會還原原始的容器與 Blob 名稱。
使用無程式碼雲端存檔將先前的遊戲移植到 PC Game Saves
您移植到 PC Game Pass 的某些遊戲可能需要無程式碼雲端存檔解決方案。在下列案例中可能會有此需求：- 遊戲以 x86 應用程式的形式執行。它只以封裝形式使用 Microsoft Game Development Kit (GDK)。
- 遊戲在沒有自訂程式碼的情況下建立，使用 Unreal Engine 中的 Blueprint 或 Unity 中的 Bolt 等工具。
- 遊戲遭到終止。
- 追蹤的使用者登出。
- PC 電源狀態變更。
- 自遊戲上次寫入指定的存檔區域後已經過 30 分鐘。
XGameSaveFiles 之上，並共用其在檔案大小與每位使用者儲存空間限制方面的所有限制。檔案上限為 64 MB (如果需要與 XGameSave 或 Connected Storage 互通，則為 16 MB)。根據預設，每位使用者的儲存空間上限為 256 MB。需要更大每位使用者儲存空間上限的遊戲，可以與其開發人員合作夥伴經理 (DPM) 合作申請例外。
目錄與檔案名稱有特定的命名慣例與字元限制。如需詳細資訊，請參閱 XGameSaveFiles 路徑邏輯。
無程式碼雲端存檔需要使用
wdapp install 將遊戲以封裝組建的形式啟動。直接啟動 .exe 不會啟用雲端存檔重新導向。封裝組建執行時，透過 NoCodePCRoot 寫入的存檔會重新導向到由 XGameSaveFiles 管理的儲存空間。之後直接啟動 .exe 時，會改為讀取實體的 NoCodePCRoot 資料夾，而該資料夾可能是空的，導致存檔看起來遺失了。若要避免此問題，請一律使用 wdapp install 以封裝組建測試無程式碼雲端存檔。啟用無程式碼雲端存檔
若要啟用無程式碼雲端存檔，請完成下列步驟：- 修改您的
MicrosoftGame.config檔案。 - 啟用簡化使用者模型。
- 指定存檔檔案的根資料夾。
- 提供遊戲對應的 SCID。
NoCodePCRoot 指定的根資料夾必須相對於少數幾個選項之一。
請使用
SavedGames 作為 RelativeTo 值。Saved Games 資料夾 (%USERPROFILE%\Saved Games) 對應到 Windows 已知資料夾識別碼 FOLDERID_SavedGames。根據預設，OneDrive 不會同步此資料夾。請避免使用其他位置，例如 AppData (%APPDATA%)。OneDrive 可能會同步這些位置，並可能與雲端存檔同步發生衝突。如需 FOLDERID_SavedGames 的詳細資訊，請參閱 SHGetKnownFolderPath。<NoCodePCRoot RelativeTo="SavedGames">savegame1.sav</NoCodePCRoot>) 是無效的，因為 savegame1.sav 會被忽略。<NoCodePCRoot> 的用途是定義目錄路徑，而不是特定檔案。