> ## 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.

# 使用覆疊資料夾進行偵錯

> 如何使用覆疊資料夾在本機偵錯並反覆修改遊戲，而不需修改底層磁碟資料夾結構中的檔案。

# 覆疊資料夾

<Note>
  一般而言，工具 SKU 可讓您從 GDK 升級工具，而不需要升級其他 GDK 元件 (例如標頭、程式庫和 Game OS)。覆疊資料夾功能是一項例外，因為它依賴 Game OS 的支援，而 Game OS 是隨 GDK 發行，而非隨工具 SKU 發行。
</Note>

## 覆疊資料夾的典型用途

覆疊資料夾非常適合遊戲開發人員想要在本機更新遊戲中的單一檔案或少數檔案，但保留原始遊戲檔案的底層儲存體不變的案例。請參考下列範例。

* Abigail 正在她的 XBOX One ERA 開發套件上測試遊戲的封裝版本。她在遊戲中遇到一個錯誤，並且知道其根本原因。她很快在開發 PC 上於本機修正了有問題的程式碼。她在開發套件上建立了一個與遊戲套件相關聯的覆疊資料夾。她將包含修正的可執行檔複製到覆疊資料夾中，啟動遊戲，然後立即就能確認修正已解決該錯誤。這大幅縮短了她的反覆開發時間。以前，她必須重新封裝整個遊戲並將套件重新部署至主機，才能測試這類修正。
* Felix 負責維護一間遊戲測試實驗室，其中的開發套件設定為可透過工作室的網路，從集中式建置伺服器上儲存的鬆散檔案建置，依需求執行各種遊戲 (使用從 PC 執行部署模型)。其中一位遊戲測試人員發現了一個嚴重錯誤。一位開發人員提供了一個私人 .dll 給 Felix，Felix 將其設定在其中一台實驗室電腦的覆疊資料夾中。覆疊該私人 .dll 之後，遊戲現在可以正常執行。Felix 能夠在一部開發套件上於本機測試修正，而不需要修改網路共用版本的遊戲，降低了干擾其他遊戲測試人員的風險。

覆疊資料夾的設計目的是讓您能夠快速、反覆地變更遊戲，即使用來安裝遊戲的原始套件無法使用或無法修改也一樣。

## 覆疊資料夾概念

開發人員可以使用覆疊資料夾，以儲存在其他位置 (包括本機磁碟機上的鬆散檔案或網路上的某處) 的替代版本，\_覆疊\_或取代遊戲中某個檔案的版本。若要成功使用覆疊資料夾，您需要了解下列核心概念：

* **Set (設定)：** 將遊戲的套件完整名稱與將儲存覆疊檔案的資料夾路徑相關聯。設定後，套件完整名稱和路徑基本上會形成一個索引鍵/值組，並在開發套件重新開機後持續保留。
* **Get (取得)：** 擷取目前與特定套件完整名稱相關聯的覆疊資料夾路徑。
* **List (列出)：** 列出開發套件上註冊的所有套件完整名稱 (PFN)/覆疊資料夾路徑組。
* **Clear (清除)：** 您可以清除 (也稱為\_重設\_) 特定套件完整名稱或所有套件完整名稱的覆疊資料夾。這只會移除先前與套件完整名稱相關聯的任何覆疊資料夾路徑。

讓我們用一個範例來說明這些概念。Omar 正在測試一款名為 MyGame 的遊戲。遊戲的主要可執行檔是 MyGame.exe，它會作為遊戲啟動區塊的一部分安裝。遊戲的其他部分可以在遊戲執行時載入，因此它們位於啟動區塊安裝後才串流至主機的區塊中。installlazily.dll 是一個可能在遊戲啟動後串流至主機的二進位檔。開發人員 Eugenia 修正了昨晚 MyGame 封裝建置中的幾個錯誤，並希望 Omar 測試這些修正。他可以使用覆疊資料夾，輕鬆地設定測試這些修正，甚至不需要請 Eugenia 重新封裝 MyGame，步驟如下。

1. Omar 使用 GDK 命令提示字元，在其 XBOX 開發套件的系統暫存磁碟機上建立新資料夾。
   ```text theme={null}
   @REM Create the overlay folder on the devkit's system scratch drive.
   mkdir \\MyDevKit\SystemScratch\MyGameOverlay\
   ```
2. 接著，他將已修正的二進位檔複製到新建立的覆疊資料夾中。
   ```text theme={null}
   @REM Copy two files to the overlay folder on the console.
   copy c:\Development\MyGame\game.exe \\MyDevKit\SystemScratch\MyGameOverlay\
   copy c:\Development\MyGame\installlazily.dll \\MyDevKit\SystemScratch\MyGameOverlay\
   ```
3. 然後，Omar 將他的資料夾設定為遊戲的覆疊資料夾。
   ```text theme={null}
   @REM Register the overlay folder for the package. Because it's in the scratch drive, it's relative to D:\ on the console
   xbapp overlayfolder MyGame_1.0.0.0_neutral__cw5n1h2txyewy xD:\MyGameOverlay
   ```
4. 最後，他從昨晚的套件建置安裝啟動區塊。
   ```text theme={null}
   @REM Install the package's launch chunk and register the game.
   xbapp install /l c:\Development\MyGame\Packages\MyGame_1_0_0_0.xvc
   ```
5. 現在他已準備好進行測試。他照常啟動遊戲。

遊戲啟動時，會載入覆疊資料夾中的 game.exe (也就是說，不是作為套件啟動區塊的一部分複製到主機的 game.exe)。當串流安裝進行到包含 installlazily.dll 的區塊已安裝時，遊戲會收到該區塊可用的通知，並載入 installlazily.dll。系統將會載入覆疊資料夾中的 installlazily.dll 版本。因此，覆疊資料夾中已修正的二進位檔讓未修改的套件能夠正常執行，而 Omar 回報問題已解決。

## 設計影響

開發套件會代表開發人員以透明的方式執行大量工作，讓覆疊資料夾易於使用。雖然這些作業是透明的，但仍有一些層面是您應該了解的，以便從覆疊資料夾獲得最大效益。

### 彈性的工作流程

在上一個範例中，Omar 決定先設定覆疊資料夾，然後再安裝昨晚的封裝建置。他也可以決定先安裝套件。只要包含覆疊檔案的資料夾存在且可以存取，且已設定覆疊資料夾將遊戲的套件完整名稱與覆疊資料夾路徑相關聯，在開發人員嘗試啟動遊戲時遊戲已安裝/註冊，就會使用覆疊資料夾中的檔案來執行遊戲。這些作業的順序由開發人員決定。

* 設定覆疊資料夾時，遊戲不需要已安裝/註冊。
* 設定覆疊資料夾時，覆疊資料夾路徑中參照的目錄不需要存在或可以存取。
* 新增至覆疊資料夾的新檔案和目錄 (包括在遊戲執行期間新增的)，會在遊戲執行時用於後續的 FileOpen 呼叫。
* 設定覆疊後解除安裝/重新安裝遊戲不會造成任何副作用。

<Note>
  目前不支援在覆疊資料夾中覆寫遊戲的 MicrosoftGame.config。
</Note>

### 開發工具的選擇

在上一個範例中，Omar 在 XBOX 開發套件上建立了一個目錄，並使用 GDK 命令提示字元 (也就是使用 mkdir 和 copy) 將檔案複製到其中。他也可以選擇使用其他工具。

* GDK 遠端工具 (例如 xbdir 和 xbcp)
* Windows 圖形化工具 (例如檔案總管)
* Bash 殼層命令
* 協力廠商工具

同樣地，Omar 是在命令列上使用 xbapp 設定覆疊資料夾。覆疊資料夾設定也可以透過下列方式進行：

* XBOX Manager
* XBOX Device Portal
* Developer Home (Dev Home)
* XBOX Tools Framework API

### 透明的作業與診斷

#### 視覺指示器

覆疊資料夾很容易「設定後就忘記」。設定覆疊資料夾後，可以在不變更覆疊資料夾設定的情況下，新增/更新/移除其中的檔案和目錄。因此，我們在圖形化工具中提供視覺提示，主動提醒開發人員他們已為遊戲設定了覆疊資料夾。

#### 偵錯輸出

當遊戲啟用且已為其套件完整名稱設定覆疊資料夾時，系統會寫入偵錯輸出以反映已找到覆疊，同時也會輸出從覆疊資料夾載入的檔案。

## 設定覆疊資料夾

### 從命令列設定覆疊資料夾

如本主題上一節所示，您可以使用 [xbApp overlayfolder](/zh-TW/tools/tools-console/commandlinetools/xbapp) 命令，擷取、設定、更新和重設指定套件完整名稱的覆疊資料夾。

### 從 XBOX Manager 設定覆疊資料夾

XBOX Manager 提供檢視、新增和刪除套件完整名稱之覆疊資料夾路徑的功能。如需詳細資訊，請參閱[管理應用程式和檔案 (XBOX Manager)](/zh-TW/tools/tools-console/xbom/manager-tool-managing-applications)。

### 從 XBOX Device Portal 設定覆疊資料夾

XBOX Device Portal 提供檢視、新增和刪除套件完整名稱之覆疊資料夾路徑的功能。如需詳細資訊，請參閱[管理覆疊資料夾 (XBOX Device Portal)](/zh-TW/tools/tools-console/wdp/windows-device-portal-on-xbox-overlay-folders)。

### 從 Dev Home 設定覆疊資料夾

Dev Home 提供檢視、新增和刪除套件完整名稱之覆疊資料夾路徑的功能。如需詳細資訊，請參閱[管理覆疊資料夾 (Dev Home)](/zh-TW/tools/tools-console/devhome/devhome-overlay-folders)。

### 使用 XBOX Tools Framework (XTF) API 設定覆疊資料夾

XTF 提供查詢、新增和清除套件完整名稱之覆疊資料夾路徑的功能。如需詳細資訊，請參閱[其他 Xtf API](/zh-TW/reference/tools/xtf/xtfapi/atoc-xtfapi)。

### 設定相對於主機的路徑

覆疊資料夾路徑採用相對於主機的觀點。如果指定 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) 可能是最佳選擇。它可讓主機使用覆疊，而不需綁定您的 PC。如果您需要取代大量檔案，使用第 1 或第 2 個選項可能會比較容易。

### 覆疊資料夾對效能的影響

覆疊資料夾會為每次開啟檔案增加少許成本。如果覆疊設定為 System OS 位置 (上一節中的選項 3)，成本會低得多。這是因為每次針對 G:\ 開啟遊戲檔案時，都會先在 System OS 中進行查詢，以確認覆疊資料夾是否包含該路徑。無論特定檔案是否有覆疊，都會產生這項成本。

如果覆疊資料夾位於開發 PC 上，效能影響應視為與透過從 PC 執行來執行遊戲相當。每次讀取檔案時，系統都會檢查覆疊資料夾，以判斷其中是否有應改為讀取的檔案；如果有，則會從開發 PC 將其提取至開發套件。將覆疊資料夾用於資料夾部署和套件安裝時，建議使用開發套件上 System Scratch 中的覆疊資料夾，以避免此成本。

### 在遊戲執行時設定覆疊

覆疊資料夾會在磁碟區對應時套用，因此需要重新啟動遊戲才能套用新的覆疊。若要事先設定讓遊戲存取，可以將一個空資料夾設定為遊戲的覆疊，之後再將檔案新增至其中。如上一節所述，這個空的覆疊資料夾仍會產生少許效能負擔。

### 將覆疊資料夾用於啟動區塊套件安裝

覆疊資料夾支援在啟動區塊套件安裝 (只安裝套件的一部分) 上覆疊檔案。在此案例中，應使用 /W 旗標執行 `xbapp install`。

對於套件可能在初始 'xbapp install' 完成後要求額外區塊的任何安裝，都需要 /W。在此案例中，啟動遊戲時將會要求啟動區塊之後的區塊。

### 安全性考量

#### 存取覆疊資料夾

在開發人員 PC 上設定覆疊資料夾時，必須明確授與主機存取開發人員 PC 上該資料夾的權限。在開發 PC 上執行的 XRFS 服務，只會允許主機從已新增至其存取清單的本機資料夾擷取檔案。可以使用如下的命令列，將覆疊資料夾新增至 XRFS 存取清單。

```text theme={null}
@REM On the development PC, add the local overlay folder to the XRFS Service's "allow list."
C:\>xrfssvc.exe /paths:add=C:\overlayfolders\MyGame1  
```

在覆疊資料夾不在開發套件上的任何案例中，都必須設定允許清單。

#### 存取網路共用上的覆疊資料夾

存取位於網路共用上的覆疊資料夾時，必須確保具有網路共用存取權限的使用者認證已在開發套件上註冊。這可以使用 [xbCred](/zh-TW/tools/tools-console/commandlinetools/xbcred) 命令，或 XBOX Manager 和 XBOX Device Portal 中的同等功能來達成。

## 另請參閱

* [XBOX 遊戲開發：環境和工具](/zh-TW/tools/tools-console/gc-tools-console-toc)
* [將遊戲部署至 XBOX 開發套件](/zh-TW/home/setup-install/concepts/deployment)


## Related topics

- [XtfSetOverlayFolder](/zh-TW/reference/tools/xtf/xtfapi/functions/xtfsetoverlayfolder-xtfapi-xbox-windows-m.md)
- [XtfClearAllOverlayFolders](/zh-TW/reference/tools/xtf/xtfapi/functions/xtfclearalloverlayfolders-xtfapi-xbox-windows-m.md)
- [XtfGetOverlayFolder](/zh-TW/reference/tools/xtf/xtfapi/functions/xtfgetoverlayfolder-xtfapi-xbox-windows-m.md)
- [管理覆疊資料夾](/zh-TW/tools/tools-console/devhome/devhome-overlay-folders.md)
- [管理套件 (wdapp.exe)](/zh-TW/tools/tools-console/console_commandlinetools/wdapp.md)