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

# ATG 系統合作檢查清單

> 與 XBOX 進階技術小組合作處理 CPU、記憶體及載入時間問題的檢查清單：請先蒐集分析工具擷取、符號及重現步驟。

針對非圖形的效能問題 (CPU 使用率、系統、記憶體、載入)，請與 **XBOX 進階技術小組 (ATG)** 合作。本檢查清單涵蓋您在合作前應準備的工具、擷取及中繼資料。

<Note>
  在與 ATG 合作之前，請一律先透過您的開發人員關係聯絡人 / DPM。他們提供的資源可能在問題提報之前就協助您解決問題。
</Note>

## 前置作業：先執行執行緒調查

在與 ATG 合作之前，請先逐步完成 [**尋找執行緒問題**](/zh-TW/build/core-features/common/async/async-programming-model)。這些步驟與 ATG 在合作開始時執行的第一步相同，而您最了解自己的程式碼和預期行為，因此由您的團隊先行調查，通常能更快找出熱點。

接著請與您的**開發人員合作夥伴經理 (DPM)** 協調。他們會設定合作範圍，並擔任您的聯絡窗口。

## 理想的提供資訊

請在**數天前**將下列內容提供給 ATG，以便在正式開始日期之前解決任何問題：

* 遊戲的**可運作分析組建** (含 PIX 標記)
* 組建中每個可執行檔和 DLL 的**符號 (PDB)**
* 如果執行遊戲需要，請在對應的沙箱中提供至少**五個使用者帳戶**
* **有問題區域**的清單，以及跳至各區域的偵錯命令
* **已知在預算內區域**的清單，作為基準
* **已知問題**的清單，以及進行中的解決方案
* **高階架構概觀** (預期的執行緒親和性、優先順序、預算)
* 開發團隊中的**聯絡人** (姓名 + 電子郵件)，以處理後續問題

### 遊戲的可運作組建

可運作的組建讓 ATG 能以最相關的選項自行擷取，並根據先前擷取所揭示的內容，反覆進行聚焦的擷取。請提供所有可執行檔和 DLL 的對應符號。

若需要沙箱測試帳戶，請自行在 Partner Center 中產生；如果您沒有直接存取權，請詢問您的 DPM。

### 有問題的區域與基準區域

請提供可直接跳至已知熱點的偵錯命令或可重現步驟。由於 ATG 無從得知您遊戲的預算，將熱點與**在預算內執行的區域**搭配提供，可為他們提供關鍵的比較基準。

### 其他

* 列出已知問題，避免 ATG 重複工作。
* 提供調查期間可詢問問題的**聯絡人**。
* 包含架構 / 預算概觀 (執行緒親和性、優先順序、記憶體集區)。

## 擷取

如果無法提供可運作的組建，請提供已知有問題區域的 **PIX 擷取**以及對應的符號。

### 擷取長度

* 理想長度：**15–30 秒**。
* 若為突增情況，請包含突增**前後數秒**的內容。
* 如果需要追蹤啟動行為，請使用 **Capture Title Startup**。
* 所有擷取都應針對**已封裝的組建**進行。

### 建議的 PIX Timing 擷取選項

最低設定：

* **File Accesses**：分析載入模式時所需。
* **Memory**：至少前三個選項，用於配置模式分析。
* **GPU timings**：僅在遊戲以**檢測圖形驅動程式**啟動時可用 (在程式碼中設定，或透過 XBOX Manager 主機設定覆寫)。

### 自訂配置器

如果您的遊戲使用自訂記憶體配置器，請使用 GDK 自訂配置器事件加以標記：

* [`PIXRecordMemoryAllocationEvent`](/zh-TW/reference/tools/pix3/functions/pixrecordmemoryallocationevent)
* [`PIXRecordMemoryFreeEvent`](/zh-TW/reference/tools/pix3/functions/pixrecordmemoryfreeevent)

在 Timing 擷取選項中啟用 **Custom allocator events**。

### 等待符號處理

儲存擷取之前，請讓 PIX 完成符號處理 (進度列會出現在右上角)。在處理完成前儲存會觸發警告，並產生較難分享的擷取。

## PIX 事件、標記和執行緒名稱

Timing 擷取需要具備足夠細微度的 PIX 事件 / 標記，才能識別時間花費在哪裡。紀律很重要：

* 注意未成對的 **`PIXBeginEvent` / `PIXEndEvent`**，它們會使擷取失效。建議使用 **`PIXScopedEvent`**，它會在離開範圍時關閉。
* 除非需要 DBCS，否則請使用 **CHAR (ANSI)** 版本的 PIX 事件，其記憶體用量為 WCHAR 版本的一半。
* 使用**細微的標記** (細至每個實體更新的層級)，以便找出熱點。
* 為事件提供**描述性名稱**，並盡可能包含資產名稱。
* 將**自旋迴圈**包在事件中，讓 ATG 能測量閒置 / 停滯時間。
* 為主要階段新增**高階事件**：模擬、轉譯、背景工作、串流。
* 使用 [`SetThreadDescription`](https://learn.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreaddescription) **為遊戲建立的每個執行緒命名**。PIX 和 Visual Studio 都會顯示這些名稱，您的遊戲也可以透過 `GetThreadDescription` 讀回這些名稱。

## 摘要

高品質的效能資料是合作是否有成效的關鍵。ATG 首先要求的就是上述擷取和中繼資料，事先準備好可加速整個合作過程。如有疑慮，寧可提供更多資料。

## 相關 API 文件

* [PIX3 API 參考](/zh-TW/reference/tools/pix3/pix3_members)：`PIXBeginEvent` / `PIXEndEvent` / `PIXScopedEvent` / `PIXRecordMemoryAllocationEvent` / `PIXRecordMemoryFreeEvent`。

## 相關內容

* [ATG 合作概觀](/zh-TW/build/atg-engagement/atg-engagement)
* [ATG 圖形合作檢查清單](/zh-TW/build/atg-engagement/atg-graphics-engagement)
* [尋找執行緒問題](/zh-TW/build/core-features/common/async/async-programming-model)
* [PIX Timing 擷取](/zh-TW/tools/tools-console/pix/new-timing-captures)
* [PIX for XBOX](/zh-TW/tools/tools-console/pix/pix)


## Related topics

- [存取 GDK 資源與下載](/zh-TW/home/onboarding-access/access-resources.md)
- [NDA 主題目錄 - Microsoft Learn 線上連結](/zh-TW/nda/nda-topic-directory.md)
- [XBOX 合作夥伴加入流程:取得存取權限與發行](/zh-TW/home/onboarding.md)
- [移植總覽](/zh-TW/paths/porting/overview.md)
- [媒體驗證測試步驟](/zh-TW/publishing/game-publishing/concepts/certification/certification-media-validation-test-steps.md)