Agentic coding でゲーム移植を speedrun する

ハイライト

Game Porting Toolkit 4 は agentic skills を導入し、AI コーディングアシスタントにゲーム移植の専門知識を与えます。D3D12 ゲームを Metal 4 に移植する期間を数か月から数日へ短縮し、gpudebug ツールを使って GPU レンダリング問題を自律的に診断できるようにします。

主要内容

D3D12 ゲームを Apple プラットフォームへ移植する従来の流れでは、作業量の見積もり、プロジェクトの起動、シェーダー変換、レンダラーの立ち上げ、入力の再マッピング、ネイティブプラットフォーム体験の最適化、パフォーマンス調整といった作業が必要でした。各ステップには深い Metal 知識が必要で、全体では数か月かかることも珍しくありません。

Game Porting Toolkit 4 は、新しい agentic skills のセットを提供し、AI コーディングアシスタントが移植に必要な専門知識を持てるようにします。これらの skill は 2 種類に分かれます。Expert skills は技術的な guidance を提供し、Workflow skills は構造化された進め方を提供します。Porting assistant agent は移植プロセス全体を編成し、適切なタイミングで適切な skill を読み込む役割を担います。

今回のデモでは、Microsoft の MiniEngine というオープンソース D3D12 エンジンを Windows から macOS に移植します。完全な流れには、ウィンドウの作成、Metal 4 によるレンダラーの起動、ゲームコントローラー対応の追加、MetalFX の統合が含まれます。

移植プロセスは 3 つの段階に分かれます。Discover workflow skill はコードベースを分析し、評価環境から参照キャプチャを取得し、ユーザーの preference を確認します。その後、移植対象全体は通常 1 セッションでは完了できないため、ユーザーとアシスタントが milestone 目標を計画します。各 milestone の後、agent は検証チェックを実行します。アプリが正常に起動するか、Metal validation に通るか、見た目が正しいか、コードに antipattern がないか、メモリ問題がないか、などです。

Metal 4 では明示的なメモリ管理と新しい command 構造が導入されました。既存のモデルはこの領域に知識の抜けがあり、skills はそこを埋めるために作られています。たとえば Metal 4 では定数を buffer 経由で渡し、skill は agent に推奨される割り当てパターンを教えます。また、すべての resource は GPU からアクセスされる前に residency set に登録する必要があります。skill を持たない agent はこの手順を飛ばしてしまい、レンダリングエラーを引き起こす可能性があります。

シェーダー変換にも注意点があります。D3D12 の root signature は Metal shader converter runtime を通して Metal の argument buffer にマッピングする必要があります。Skill は、index にサイズを掛けて計算するのではなく、runtime から argument buffer の offset を問い合わせるよう agent に教えます。そうしないと、layout が一致しない場合にレンダリングが静かに壊れることがあります。

同期モデルはさらに大きく異なります。D3D12 と Metal 4 は異なる barrier model を使うため、skill は対応表を提供します。Agent は広い blanket barrier を使うのではなく、MtlProducerStageFromD3D12 と MtlConsumerStageFromD3D12 関数で状態をマッピングします。

特に注目すべきなのは、macOS 27 で追加された command-line ツールです。gpucapture は GPU frame をキャプチャし、gpudebug はそのキャプチャを分析します。これにより agent はレンダリング問題を自律的にデバッグできます。デモでは SSAO は正常に動作している一方で、ライティングとテクスチャに問題がありました。Agent は debugging rendering issues skill を読み込み、gpucapture で frame を取得し、gpudebug で resource binding、定数、resource 内容、data flow を調べ、最終的に問題を特定して修正します。

最後のデモでは、Godot エンジンを Metal 3 から Metal 4 にアップグレードする様子も示されます。同じ workflow、同じ skills、同じ検証プロセスで、数日以内に完了しました。これは skills が production-grade のプロジェクトにも拡張できることを示しています。

詳細

インストールと起動

（03:31）

Skills と assistant は plugin として提供され、GitHub 上の Game Porting Toolkit marketplace からインストールします。

/plugin marketplace add apple/game-porting-toolkit
/plugin install game-porting-skills@game-porting-toolkit

インストール後は、porting assistant に直接 guidance を求められます。アシスタントは構造化された workflow に沿って案内します。

Resource 管理

（10:24）

Metal 4 では、使用前にすべての GPU resource を residency set に登録する必要があります。

// Skill がある場合
residencySet->addAllocation(texture);
residencySet->commit();
// ...
argumentTable->setAddress(texture->gpuAddress(), bindPoint);

// Skill がない場合
argumentTable->setAddress(texture->gpuAddress(), bindPoint);

ポイント:

• residencySet->addAllocation() は texture を residency 管理に追加します。
• residencySet->commit() は登録を commit し、GPU がその resource にアクセスできることを保証します。
• skill を持たない agent はこの手順を飛ばし、GPU が texture を正しく読めなくなる可能性があります。

Argument buffer offset の問い合わせ

（11:25）

Metal shader converter を使う場合、argument buffer の layout は想定と異なる可能性があるため、runtime から問い合わせる必要があります。

// Skill がある場合
IRRootSignatureGetResourceLocations(m_MtlCurIRRootSig, locations);
size_t offset = locations[i].topLevelOffset;

// Skill がない場合
size_t offset = paramIndex * descriptorSize;

ポイント:

• IRRootSignatureGetResourceLocations() は shader converter runtime から実際の resource 位置を取得します。
• locations[i].topLevelOffset が本当の offset です。
• shader converter 使用時に paramIndex * descriptorSize を手計算すると誤る可能性があります。

同期状態のマッピング

（12:34）

D3D12 の状態は Metal 4 の producer-consumer model にマッピングする必要があります。

// Skill がある場合
m_MtlPendingProducerStages |= MtlProducerStageFromD3D12(OldState);
m_MtlPendingConsumerStages |= MtlConsumerStageFromD3D12(NewState);
// ...
m_ComputeEncoder->barrierAfterStages(
    m_MtlPendingProducerStages,
    m_MtlPendingConsumerStages,
    MTL4::VisibilityOptionDevice);

// Skill がない場合
m_ComputeEncoder->barrierAfterStages(
    MTL::StageDispatch,
    MTL::StageAll,
    MTL4::VisibilityOptionDevice);

ポイント:

• MtlProducerStageFromD3D12() は D3D12 状態を Metal producer stage にマッピングします。
• MtlConsumerStageFromD3D12() は consumer stage にマッピングします。
• StageAll のような広い barrier を使うより、正確なマッピングのほうが効率的で安全です。

Shader reflection の問い合わせ

（14:24）

Parameter 数を hard-code せず、shader reflection から実際の数を問い合わせます。

// Skill がある場合
IRShaderReflection* refl = IRShaderReflectionCreate();
IRObjectGetReflection(compiledObj, IRShaderStageCompute, refl);
// ...
s_RootSignature.Reset(4, 2); // Reflection により 4 個の params と判明

// Skill がない場合
s_RootSignature.Reset(5, 2);

ポイント:

• IRShaderReflectionCreate() は reflection object を作成します。
• IRObjectGetReflection() は compile 済み shader から reflection を取得します。
• hard-code した parameter 数ではなく、reflection の結果に基づいて root signature を初期化します。

GPU デバッグツール

（16:02）

macOS 27 の新しい command-line ツールにより、agent は自律的にデバッグできます。

# GPU frame をキャプチャ
gpucapture

# キャプチャを分析
gpudebug

Agent は resource binding、定数、resource 内容、data flow を検査し、評価環境の参照キャプチャと比較しながら、体系的に問題を特定できます。

MetalFX 統合

（21:00）

MetalFX upscaling skill は、jitter 設定、motion vector、history reprojection といった複雑な統合作業を扱います。Frame interpolation skill は独立した presentation thread、正確な timing 制御、正しい presentation order を設定します。

macOS 27 では Metal HUD の機能が拡張され、upscaler の exposure parameter や jitter sequence 情報を表示できるようになりました。また、motion vector や jitter multiplier をデバッグするための overlay option も提供されます。

主要な示唆

1. 自動移植検証 workflow — gpudebug ツールを使って移植前後の GPU capture を自動比較し、dispatch call、pipeline state、resource binding が一致しているかを確認し、各 milestone の検証を自動化します。

2. Metal 4 メモリ管理 best practice チェッカー — 既存プロジェクト向けの静的解析ツールを作り、residency set に登録されていない resource や、argument buffer offset を手計算している箇所を scan し、更新が必要な場所を自動で示します。

3. ゲームコントローラー動的発見デモ — Game Controller skill の考え方で小さなアプリを作り、接続された controller の layout と利用可能な input を real-time に表示します。controller capability を hard-code せず問い合わせる方法を示せます。

4. MetalFX デバッグ検証パネル — Metal HUD の新しい overlay option を使って runtime debug panel を作り、jitter multiplier と motion vector scale を real-time に調整できるようにし、upscaling 統合のデバッグを支援します。

5. Shader reflection 差分分析ツール — D3D12 root signature と Metal shader converter が生成した argument buffer layout を比較し、parameter 数の不一致や offset 差分などの潜在問題を自動検出します。

関連 Session

• Go further with Metal 4 games — Metal 4 ゲーム開発の深掘り
• Metal neural rendering — Metal の neural rendering 技術
• Metal performance — Metal のパフォーマンス最適化
• Immersive environments — 没入型 environment のレンダリング
• RealityKit — RealityKit フレームワークの更新