覆疊資料夾
一般而言，工具 SKU 可讓您從 GDK 升級工具，而不需要升級其他 GDK 元件 (例如標頭、程式庫和 Game OS)。覆疊資料夾功能是一項例外，因為它依賴 Game OS 的支援，而 Game OS 是隨 GDK 發行，而非隨工具 SKU 發行。
覆疊資料夾的典型用途
覆疊資料夾非常適合遊戲開發人員想要在本機更新遊戲中的單一檔案或少數檔案，但保留原始遊戲檔案的底層儲存體不變的案例。請參考下列範例。- Abigail 正在她的 XBOX One ERA 開發套件上測試遊戲的封裝版本。她在遊戲中遇到一個錯誤，並且知道其根本原因。她很快在開發 PC 上於本機修正了有問題的程式碼。她在開發套件上建立了一個與遊戲套件相關聯的覆疊資料夾。她將包含修正的可執行檔複製到覆疊資料夾中，啟動遊戲，然後立即就能確認修正已解決該錯誤。這大幅縮短了她的反覆開發時間。以前，她必須重新封裝整個遊戲並將套件重新部署至主機，才能測試這類修正。
- Felix 負責維護一間遊戲測試實驗室，其中的開發套件設定為可透過工作室的網路，從集中式建置伺服器上儲存的鬆散檔案建置，依需求執行各種遊戲 (使用從 PC 執行部署模型)。其中一位遊戲測試人員發現了一個嚴重錯誤。一位開發人員提供了一個私人 .dll 給 Felix，Felix 將其設定在其中一台實驗室電腦的覆疊資料夾中。覆疊該私人 .dll 之後，遊戲現在可以正常執行。Felix 能夠在一部開發套件上於本機測試修正，而不需要修改網路共用版本的遊戲，降低了干擾其他遊戲測試人員的風險。
覆疊資料夾概念
開發人員可以使用覆疊資料夾，以儲存在其他位置 (包括本機磁碟機上的鬆散檔案或網路上的某處) 的替代版本，_覆疊_或取代遊戲中某個檔案的版本。若要成功使用覆疊資料夾，您需要了解下列核心概念：- Set (設定)： 將遊戲的套件完整名稱與將儲存覆疊檔案的資料夾路徑相關聯。設定後，套件完整名稱和路徑基本上會形成一個索引鍵/值組，並在開發套件重新開機後持續保留。
- Get (取得)： 擷取目前與特定套件完整名稱相關聯的覆疊資料夾路徑。
- List (列出)： 列出開發套件上註冊的所有套件完整名稱 (PFN)/覆疊資料夾路徑組。
- Clear (清除)： 您可以清除 (也稱為_重設_) 特定套件完整名稱或所有套件完整名稱的覆疊資料夾。這只會移除先前與套件完整名稱相關聯的任何覆疊資料夾路徑。
- Omar 使用 GDK 命令提示字元，在其 XBOX 開發套件的系統暫存磁碟機上建立新資料夾。
- 接著，他將已修正的二進位檔複製到新建立的覆疊資料夾中。
- 然後，Omar 將他的資料夾設定為遊戲的覆疊資料夾。
- 最後，他從昨晚的套件建置安裝啟動區塊。
- 現在他已準備好進行測試。他照常啟動遊戲。
設計影響
開發套件會代表開發人員以透明的方式執行大量工作，讓覆疊資料夾易於使用。雖然這些作業是透明的，但仍有一些層面是您應該了解的，以便從覆疊資料夾獲得最大效益。彈性的工作流程
在上一個範例中，Omar 決定先設定覆疊資料夾，然後再安裝昨晚的封裝建置。他也可以決定先安裝套件。只要包含覆疊檔案的資料夾存在且可以存取，且已設定覆疊資料夾將遊戲的套件完整名稱與覆疊資料夾路徑相關聯，在開發人員嘗試啟動遊戲時遊戲已安裝/註冊，就會使用覆疊資料夾中的檔案來執行遊戲。這些作業的順序由開發人員決定。- 設定覆疊資料夾時，遊戲不需要已安裝/註冊。
- 設定覆疊資料夾時，覆疊資料夾路徑中參照的目錄不需要存在或可以存取。
- 新增至覆疊資料夾的新檔案和目錄 (包括在遊戲執行期間新增的)，會在遊戲執行時用於後續的 FileOpen 呼叫。
- 設定覆疊後解除安裝/重新安裝遊戲不會造成任何副作用。
目前不支援在覆疊資料夾中覆寫遊戲的 MicrosoftGame.config。
開發工具的選擇
在上一個範例中，Omar 在 XBOX 開發套件上建立了一個目錄，並使用 GDK 命令提示字元 (也就是使用 mkdir 和 copy) 將檔案複製到其中。他也可以選擇使用其他工具。- GDK 遠端工具 (例如 xbdir 和 xbcp)
- Windows 圖形化工具 (例如檔案總管)
- Bash 殼層命令
- 協力廠商工具
- XBOX Manager
- XBOX Device Portal
- Developer Home (Dev Home)
- XBOX Tools Framework API
透明的作業與診斷
視覺指示器
覆疊資料夾很容易「設定後就忘記」。設定覆疊資料夾後，可以在不變更覆疊資料夾設定的情況下，新增/更新/移除其中的檔案和目錄。因此，我們在圖形化工具中提供視覺提示，主動提醒開發人員他們已為遊戲設定了覆疊資料夾。偵錯輸出
當遊戲啟用且已為其套件完整名稱設定覆疊資料夾時，系統會寫入偵錯輸出以反映已找到覆疊，同時也會輸出從覆疊資料夾載入的檔案。設定覆疊資料夾
從命令列設定覆疊資料夾
如本主題上一節所示，您可以使用 xbApp overlayfolder 命令，擷取、設定、更新和重設指定套件完整名稱的覆疊資料夾。從 XBOX Manager 設定覆疊資料夾
XBOX Manager 提供檢視、新增和刪除套件完整名稱之覆疊資料夾路徑的功能。如需詳細資訊，請參閱管理應用程式和檔案 (XBOX Manager)。從 XBOX Device Portal 設定覆疊資料夾
XBOX Device Portal 提供檢視、新增和刪除套件完整名稱之覆疊資料夾路徑的功能。如需詳細資訊，請參閱管理覆疊資料夾 (XBOX Device Portal)。從 Dev Home 設定覆疊資料夾
Dev Home 提供檢視、新增和刪除套件完整名稱之覆疊資料夾路徑的功能。如需詳細資訊，請參閱管理覆疊資料夾 (Dev Home)。使用 XBOX Tools Framework (XTF) API 設定覆疊資料夾
XTF 提供查詢、新增和清除套件完整名稱之覆疊資料夾路徑的功能。如需詳細資訊，請參閱其他 Xtf API。設定相對於主機的路徑
覆疊資料夾路徑採用相對於主機的觀點。如果指定 E:\Overlay，主機會在 System OS 中尋找 E:\Overlay，並且找不到它。這是由於覆疊的處理方式所致：負責處理覆疊的是 System OS 和 Title OS，而不是 PC 工具。 若要正確設定覆疊資料夾，請使用下列指引。- 您可以透過 SMB 共用覆疊資料夾，然後使用 \FQDN_PC_NAME\shared_overlay 路徑：
- 範例：
xbapp.exe overlayfolder bo5-dev_1.0.0.0_neutral__ht1qfjb0gaftw \FQDN_PC_NAME\shared_overlay - 注意：主機需要透過
xbcred add FQDN_PC_NAME\shared_overlay FQDN\USER_NAME PASSWORD取得 SMB 共用的認證 - 注意：在所有參照此路徑的地方，您都應使用完整網域名稱，以避免名稱解析問題。
- 範例：
- 您可以透過 XBTPLink 使用從 PC 執行，使用 xbtp:\FQDN\Q:\overlay
- 範例：
xbapp.exe overlayfolder bo5-dev_1.0.0.0_neutral__ht1qfjb0gaftw Q:\overlay - 注意：您需要確保 XbtpLinkSvc.exe 已啟動，且防火牆允許 TCP 連接埠 4201 連線至它。
- 注意：在 2021 年 10 月之前的 GDK 版本中，必須使用 xbtp:\FQDN_PC_NAME\ 來建立覆疊資料夾的 xbtp 路徑，現在已不再需要，只要指定網路資料夾的路徑即可。
- 範例：
- 您可以使用 System OS 中的 D:\，透過 xbcp 複製檔案：
xbcp Q:\overlay\mygame.exe xd:\overlay\- 範例：
xbapp.exe overlayfolder bo5-dev_1.0.0.0_neutral__ht1qfjb0gaftw xD:\overlay - 注意：在此情況下，您將使用 xD:\overlay 作為覆疊資料夾。
- 範例：
覆疊資料夾對效能的影響
覆疊資料夾會為每次開啟檔案增加少許成本。如果覆疊設定為 System OS 位置 (上一節中的選項 3)，成本會低得多。這是因為每次針對 G:\ 開啟遊戲檔案時，都會先在 System OS 中進行查詢，以確認覆疊資料夾是否包含該路徑。無論特定檔案是否有覆疊，都會產生這項成本。 如果覆疊資料夾位於開發 PC 上，效能影響應視為與透過從 PC 執行來執行遊戲相當。每次讀取檔案時，系統都會檢查覆疊資料夾，以判斷其中是否有應改為讀取的檔案；如果有，則會從開發 PC 將其提取至開發套件。將覆疊資料夾用於資料夾部署和套件安裝時，建議使用開發套件上 System Scratch 中的覆疊資料夾，以避免此成本。在遊戲執行時設定覆疊
覆疊資料夾會在磁碟區對應時套用，因此需要重新啟動遊戲才能套用新的覆疊。若要事先設定讓遊戲存取，可以將一個空資料夾設定為遊戲的覆疊，之後再將檔案新增至其中。如上一節所述，這個空的覆疊資料夾仍會產生少許效能負擔。將覆疊資料夾用於啟動區塊套件安裝
覆疊資料夾支援在啟動區塊套件安裝 (只安裝套件的一部分) 上覆疊檔案。在此案例中，應使用 /W 旗標執行xbapp install。
對於套件可能在初始 ‘xbapp install’ 完成後要求額外區塊的任何安裝，都需要 /W。在此案例中，啟動遊戲時將會要求啟動區塊之後的區塊。