Game Porting Toolkit 4：Mac 上的代理式遊戲移植

「I am using Claude Code for everything today.」Apple Metal Ecosystem Team 的工程師 David Srour 在 WWDC 2026 的舞台上說出這句話，接著用 session 357 剩下的時間，把 Microsoft 的 MiniEngine 從 Windows 上的 D3D12 移植到 macOS 上的 Metal 4——而平台工作則由一個代理完成。¹ 載體是 Game Porting Toolkit 4，它以外掛形式推出代理式技能，您可以從 GitHub 上的 Game Porting Toolkit marketplace 安裝：承載平台知識的專家技能、施加以里程碑為基礎流程的工作流程技能，以及協調兩者的移植助理代理。¹ Apple 也打造了讓這場示範得以成真的基礎元件。macOS 27 新增了 gpucapture 與 gpudebug 這兩個命令列工具，讓代理無須由人操作 Xcode，就能擷取並分析一個 GPU 影格。¹

Apple 為一個程式設計代理發布了第一方技能包，瞄準的是代理過去無法獨力觸及的領域：啟動算繪器、為錯誤的像素除錯，以及調校升頻器。Session 356 是它的姊妹篇，由 CD PROJEKT RED 的 Paweł Sasko 講解該工作室如何親手把 Cyberpunk 2077: Ultimate Edition 帶上 Mac。Cyberpunk 的移植早於這些代理式技能；CDPR 沒有任何人執行過移植助理。Apple 刻意把這兩場 session 配成一對，並在 Cyberpunk 演講的尾聲把開發者指向代理式那一場。² 兩者合讀，提出了同一個論點：手動劇本在 AAA 規模下行得通，而 Game Porting Toolkit 4 把那套劇本交到了代理手中。

重點摘要

• Game Porting Toolkit 4 為遊戲移植新增代理式技能：專家技能（領域知識）、工作流程技能（以里程碑為基礎的流程），以及協調它們的移植助理代理，並以外掛形式從 GitHub 上的 Game Porting Toolkit marketplace 發布。¹
• 工作流程依序執行 discover（程式碼庫掃描、從評估環境擷取參考、偏好提問）、plan、execute 與 validate；每個里程碑都會自動載入其專家技能，「without relying on whether the model decides to use them or not」，而且代理會「stores what it learns across milestones」。¹
• macOS 27 推出 gpucapture 與 gpudebug，這兩個 CLI 工具「support fully autonomous agent workflows」，並為 MetalFX 提供 Metal HUD 擴充功能：曝光讀數、以紅色標示超出範圍數值的抖動散佈圖，以及即時覆寫。¹
• Apple 示範這些技能，把 Microsoft 的 MiniEngine 從 D3D12 移植到 Metal 4，接著把助理指向 Godot，後者取得的 Metal 4 後端「up and running in a few days」。¹
• Cyberpunk 2077 以手動方式在 AAA 規模上驗證了底層管線：評估環境優先的剖析、「For this Mac」自動預設、透過 EDR 自動校準的 HDR，以及具頭部追蹤的空間音訊，並在 Apple 2025 年 App Store Awards 中奪得 Mac 年度遊戲。²

移植助理及其技能（Session 357）

David Srour 為他的代理命名，並從 Game Porting Toolkit marketplace 安裝外掛，從 3:26 開始。

一次典型的移植，意味著界定工作範圍、讓建置跑起來、轉換著色器、啟動算繪器、重新對映輸入、為原生質感打磨，以及最佳化效能。¹ Game Porting Toolkit 4 用兩類技能來攻克這份清單。專家技能提供技術指引：平台知識、最佳實務，以及常見移植反模式的警示。工作流程技能提供結構化的方法。移植助理代理把它們串連起來，而 Apple 明確說明了為何協調至關重要：「During execution, all planned milestones automatically load the necessary expert skills without relying on whether the model decides to use them or not.」¹ 技能的選擇不再是模型擲骰子的結果，而成為流程定義的一部分。

發布透過代理本身的外掛系統進行。「The skills and assistant are provided as a plugin from the Game Porting Toolkit marketplace on GitHub. You will first add the marketplace. And then install the plugin.」¹ 那個 marketplace 背後的儲存庫是 apple/game-porting-toolkit，描述為「Resources for porting games and engines to Apple platforms」；其 README 記載了相同的劃分：涵蓋 Metal 4、MetalFX、著色器編譯、平台框架與除錯工具的專家技能，以及執行以里程碑為基礎的移植流程、並在工作階段之間保存狀態的工作流程技能。³ 在 Claude Code 中，註冊這個 marketplace 只需一個指令：/plugin marketplace add apple/game-porting-toolkit。³

助理的工作流程分為三個階段。Discover 查看您的程式碼庫，從評估環境抓取參考擷取（也就是 CDPR 用過的那個轉譯 Windows 建置的環境，下文詳述），並就您的偏好向您提問。接著您與助理一同規劃里程碑目標，「since porting a whole title is usually too big for one session」。¹ 對於每個里程碑，代理在您的指引下執行變更，然後由 validation 跑一份多點檢查表：App 正常啟動、Metal validation 在 API 使用與著色器上通過、畫面擷取對照基準參考確認視覺正確性、代理依其用過的技能所列的已知反模式審查程式碼，並檢查記憶體問題。¹ 代理還會「stores what it learns across milestones, so nothing gets lost between sessions」。¹

MiniEngine 的示範展示了專家技能實際帶來的價值。對於第一個里程碑——一個具有正確影格節奏的視窗——四個技能一同載入：視窗建立與生命週期、swap-chain 概念對映、可繪製物件呈現，以及 metal-cpp 物件生命週期。¹ 對於場景算繪，resources 技能教授 Metal 4 的常駐模型：及早把資源註冊到 residency set 中，因為缺少這項知識，代理產生的程式碼雖能編譯，GPU 卻無法讀取該紋理。¹ 著色器管線與轉換器技能讓代理向 Metal shader converter 執行階段查詢引數緩衝區位移，而非照抄 MiniEngine 的索引乘大小算式——當轉換器以不同方式佈局緩衝區時，那套算式就會出錯：「No error, just incorrect rendering.」¹ 同步技能把 D3D12 的屏障模型對映到 Metal 4 的生產者—消費者模型，而非讓代理退回到在編碼器邊界處一律設屏障的做法——後者在簡單情況下管用，卻會隨著管線壯大而無聲地失效。¹ 三者之間浮現出一個共通的模式：技能所防範的故障型態鮮少是當機，而是沒有任何錯誤訊息的錯誤像素。

這些技能延伸到首次可遊玩之後。一個遊戲控制器技能涵蓋 GCController 探索，並教導代理查詢已連接裝置實際支援的功能，而非假設 XInput 的固定配置。¹ 兩個 MetalFX 技能處理升頻與影格內插：升頻技能在像素空間中設定抖動（採用正規化數值實際上會停用時間累積）、以正確的尺度與慣例設定動態向量，並提供 MIP bias 與歷史重投影的設定；影格內插技能則建立一條專屬的呈現執行緒，讓內插影格與算繪影格維持均勻間距。¹

Srour 以第二個程式碼庫作結：「I pointed the porting assistant at Godot, a production engine with an existing Metal 3 backend, and asked it to add Metal 4 alongside it.」¹ 相同的工作流程、相同的技能、對照基準的驗證。「It’s still a collaborative effort, but the skills sped things up significantly. It was up and running in a few days.」¹ 對於整場 session，他的分工方式正是值得向任何懷疑代理式移植的人引述的部分：「I let the skills do the heavy lifting, while I focused on other things: making the architectural decisions, reviewing the agent’s output, and providing important context about the game.」¹

gpucapture 與 gpudebug：自主除錯的基礎元件

Session 357 的關鍵時刻出現在 MiniEngine 移植的中途，當初光亮起時帶著錯誤的光照與明顯拉伸的牆面紋理。Srour 直接點出這道缺口：「Normally I’d capture a frame in Xcode and diagnose the issue. But until now, an agent couldn’t do that on its own.」¹ GPU 除錯一直是自主圖形工作的硬牆；一切都得透過 GUI。

macOS 27 推倒了這道牆：「macOS 27 introduces new command-line tools which support fully autonomous agent workflows: gpucapture for capturing a GPU frame, and gpudebug for analyzing it.」¹ 在示範中，Srour 描述視覺症狀，代理載入一個除錯算繪問題的技能，內含一套從症狀到根本原因的結構化方法論，在 App 執行時以 gpucapture 擷取一段追蹤紀錄，接著用 gpudebug 檢視「anything you’d normally check in Xcode, resource bindings, constants, resource contents, and data flow through the pipeline」，追查輸出在何處與評估環境出現分歧，直到找出並修正問題。¹ 同樣這些工具接著為驗證提供支援：代理把派發呼叫、管線與派發維度對照原始追蹤紀錄，這種並排比對被 Srour 形容為每個里程碑都用手做會很繁瑣。¹ Apple 的產品頁面把這個定位說得很明白：有了 Metal 工具的命令列存取，代理現在可以直接擷取、除錯與剖析 Metal 工作負載。³

macOS 27 也為 MetalFX 整合工作擴充了 Metal HUD。HUD 現在會顯示升頻器的曝光參數，讓您確認它確實傳到 API；會以散佈圖呈現抖動序列資訊，並把超出範圍的抖動標為紅色；還為抖動乘數與動態向量尺度提供即時覆寫，在 App 執行時即刻生效。¹ 示範中的診斷正是這項技術的俐落範例：鏡頭運動時出現晃動的偽影，HUD 顯示動態向量的 X 尺度被取了負號，在覆寫面板中翻轉它便修好了晃動，而「if the HUD overrides fix the output, that tells you where the bug is」。¹ 接著您把這項修正回溯到原始邏輯。

Cyberpunk 2077：AAA 規模下的手動劇本（Session 356）

Paweł Sasko 在一台 M5 Max MacBook Pro 上巡覽「For this Mac」預設，從 15:26 開始。

Session 356 讓 Apple Game Performance 團隊的工程師 Garrett Austin，與 CD PROJEKT RED 的 Associate Game Director Paweł Sasko 同台。² 把時間線講精確：Cyberpunk 2077: Ultimate Edition 在 Game Porting Toolkit 4 的代理式技能問世之前，就已在 Mac 上推出並奪得 Apple 2025 年 App Store Awards 的 Mac 年度遊戲。² 這場 session 中的每一步，CDPR 都是親手完成的。這場 session 之所以屬於一篇談代理式移植的文章，是因為 CDPR 親手走過的管線，正是移植助理如今所協調的那一條——評估環境、Metal shader converter、MetalFX、基準驗證——而 Apple 自己把兩者連了起來，在 Cyberpunk session 的尾聲把觀眾引向「Speedrun your game port with agentic coding」。²

CDPR 的第一步就確立了模式。「Before we started building the native path for Cyberpunk 2077 on Mac, we used Apple’s Game Porting Toolkit to evaluate the Windows build in a translated environment on macOS. This let us gain valuable insight before writing any code.」² 工作室在評估環境中跑了一組預先決定的熱點序列，並從三個角度解讀每一次執行：來自引擎內剖析器的統計影格時間資料、場景事件與追蹤紀錄之間的 Metal HUD 關聯，以及按執行緒拆解的引擎內部剖析。² 訊號很早就清楚了。在高規格硬體上，GPU 時間看來健康，而密集的城市駕駛則暴露出 CPU 壓力才是真正的熱點。這個環境甚至標示出它自身的偽影——來自即時著色器轉譯的影格時間振盪，以及看似沉重的音訊中介軟體，兩者在原生二進位檔中都消失了；Game Porting Toolkit 把它們指認出來，讓 CDPR 知道要及早調查。² 把這對映到 session 357 的 discover 階段——助理在規劃任何一個里程碑之前，先從同一個評估環境抓取參考擷取——其間的傳承直截了當。

出貨打磨正是 Mac 版本脫穎而出之處，而這從首次啟動就開始了。「For this Mac」是一套以裝置為基礎的圖形預設系統：它偵測您 Mac 中的硬體，並自動為該裝置配置設定。² CDPR 挑選了能維持影像保真度的逐裝置設定，設定 30 或 60 FPS 的目標影格率，在調校過的最低與最高解析度界線之間以 Dynamic Resolution Scaling 執行 MetalFX，為影格節奏設定 VSync，並依顯示器能力啟用 HDR，然後在一個量測—精修—再驗證的循環中，為每台裝置逐一調校其餘所有設定。² Sasko 在一台搭載 M5 Max 晶片的 MacBook Pro 上示範成果：以 Ultra 預設為基底、搭配 VSync 的 60 FPS 鎖定、Dynamic Resolution Scaling 在 2336x1460 輸出的 50% 到 80% 之間算繪，在開箱即用的設定下，穿越 Dogtown 的 Black Market——遊戲中最吃重的區域之一——維持 60 FPS。² 這個構想正在擴散：「other developers are starting to adopt ‘For this Mac’ settings in their games as well」。²

HDR 出貨時不附校準畫面。CDPR 透過 Apple 的 Extended Dynamic Range 管線實作 HDR，輪詢 maximumExtendedDynamicRangeColorComponentValue 取得顯示器目前的最大 EDR 值，並直接餵給色調對映器；該數值會隨顯示器硬體與環境條件改變，因此色調對映器始終跟隨面板實際能呈現的範圍。² 當顯示器具備足夠裕度時，HDR 預設開啟：遊戲檢查 maximumPotentialExtendedDynamicRangeColorComponentValue，並在顯示器的最大潛在 EDR 值超過 2.0 時啟用 HDR。²

音訊也獲得同樣的預設開啟待遇。Cyberpunk 的中介軟體透過 AVAudioEngine 實作 Apple 的空間音訊 API，CDPR 把 AVAudioEnvironmentNode 的 listenerHeadTrackingEnabled 屬性設為 true，為 AirPods 啟用頭部追蹤——預設開啟，無須額外設定。² Game Mode 也對同樣的硬體有所助益：它讓遊戲取得對 CPU 與 GPU 較高優先權的存取，並把 Bluetooth 取樣率加倍，降低無線控制器與 AirPods 音訊的延遲，而 macOS 會為歸類為遊戲的 App 自動啟用它。²

成果數字為這個平台定了案。Cyberpunk 2077 在所有平台上已售出 3,500 萬份，外加 Phantom Liberty 的 1,000 萬份，而 Cyberpunk 2077: Ultimate Edition 奪得 Apple 2025 年 App Store Awards 的 Mac 年度遊戲。² Sasko 的總結會是各家工作室記住的那句：「what matters is not how much work you put into something, but what the result is for our players」。²

如何開始

這兩場 session 構成一道流程：

1. 先在評估環境中跑您的 Windows 建置。無須任何程式碼，而且該環境現在支援 Metal 4，可用於相容性與效能測試。³ 依循 CDPR 的解讀：熱點序列、影格時間統計、Metal HUD 關聯，以及逐執行緒的 CPU 剖析，並把轉譯層的偽影當作已標示的線索，而非定論。²
2. 安裝技能。加入 Game Porting Toolkit marketplace 並安裝外掛；在 Claude Code 中，marketplace 的註冊是 /plugin marketplace add apple/game-porting-toolkit。¹³ 若您不確定下一步該做什麼，就問移植助理；它的第一步就是 discovery。¹
3. 與助理一同規劃里程碑，並讓驗證為每一個把關。App 啟動、Metal validation、對照基準的擷取比對、反模式審查與記憶體檢查，每個里程碑都會執行，而代理會把所學帶進下一個工作階段。¹
4. 升級到 macOS 27 以使用除錯循環。gpucapture 與 gpudebug 賦予代理自主的影格擷取與分析，而 Metal HUD 的 MetalFX 擴充功能（曝光讀數、抖動散佈圖、即時覆寫）能在遊戲執行時定位升頻器的錯誤。¹
5. 借用 Cyberpunk 的出貨檢查表。首次啟動時採用「For this Mac」風格的自動預設、以 EDR 驅動、在 2.0 潛在裕度以上預設開啟並自動校準的 HDR，以及透過 listenerHeadTrackingEnabled 的頭部追蹤空間音訊。²

常見問題

Game Porting Toolkit 4 究竟為代理新增了什麼？

三樣東西：賦予程式設計代理跨 Metal 4、MetalFX、著色器編譯、平台框架與除錯之平台知識、最佳實務與反模式警示的專家技能；施加具狀態保存之里程碑流程的工作流程技能；以及協調整套方法論、為每個里程碑自動載入正確專家技能而非把選擇留給模型的移植助理代理。¹³

移植助理執行在哪一個程式設計代理上？

Apple 的 session 示範全程執行在 Claude Code 上；Srour 表示他「using Claude Code for everything today」。¹ 這些技能以外掛形式從 GitHub 上的 Game Porting Toolkit marketplace 安裝，而該儲存庫按程式設計代理分別整理其安裝文件，並直接記載了 Claude Code 的 marketplace 指令。³

gpucapture 與 gpudebug 是什麼？

macOS 27 中的全新命令列工具。gpucapture 從執行中的應用程式擷取一個 GPU 影格；gpudebug 分析該擷取，揭露過去需要 Xcode GUI 才能取得的 resource bindings、常數、資源內容與管線資料流。Apple 打造它們，是為了讓代理工作流程能「fully autonomous」：代理現在可以從一個視覺症狀走到根本原因、再走到一個經過驗證的修正，全程無須由人擷取影格。¹

CD PROJEKT RED 移植 Cyberpunk 2077 時用了代理式技能嗎？

沒有。Cyberpunk 2077 的 Mac 移植是一項手動工作，它在 Game Porting Toolkit 4 的代理式技能問世之前就已推出，並奪得 Apple 2025 年 App Store Awards 的 Mac 年度遊戲。² 其關聯性是反向的：CDPR 的管線（評估環境優先、Metal shader converter、搭配 Dynamic Resolution Scaling 的 MetalFX、視覺的基準驗證）正是移植助理如今以代理執行的同一套劇本。¹²

「For this Mac」預設如何運作？

它偵測玩家 Mac 中的硬體，並自動為該裝置配置圖形與影像設定：30 或 60 FPS 的目標、在調校過的解析度界線內搭配 Dynamic Resolution Scaling 的 MetalFX、VSync、輸出解析度，以及依顯示器能力決定的 HDR，其餘所有設定都逐裝置手動調校。在一台 M5 Max MacBook Pro 上，這個預設以 Ultra 為基底，並在算繪 2336x1460 的 50% 到 80% 時維持鎖定的 60 FPS。²

Running Agentic AI on the Mac with MLX 涵蓋 Mac 上代理式工作的本地推論面，而 Xcode 27 Went Agentic 涵蓋 IDE 面；Game Porting Toolkit 4 則是專屬於遊戲移植的第三隻腳。Metal 4 Essentials 拆解了這些技能所瞄準的 API。完整的系列中樞是 Apple Ecosystem Series。

參考資料