/game-porting-toolkit-workflow

name: game-porting-toolkit-workflow
description: Select and operate Apple Game Porting Toolkit 3 or 4 for bringing an existing Windows game or engine to Apple platforms. Use when Codex encounters a Windows executable, Direct3D, Vulkan, DXIL, Metal Shader Converter, GPTK evaluation, a porting milestone, or the upstream game-porting-skills plugin; route native Metal renderer work to metal-game-rendering-workflow.

Game Porting Toolkit Workflow

Scope

Choose the correct GPTK lane, preserve evidence, and load Apple’s maintained GPTK 4 skills when they own the work. This is an integration skill, not a fork of Apple’s porting corpus.

Read [version-routing.md](references/version-routing.md) before choosing a toolkit or installing anything. Check the actual local Xcode, macOS, and toolkit versions; never infer them from an app bundle path.

Choose The Lane

1. Use **GPTK 3** when the immediate job is stable evaluation of an unmodified Windows binary, baseline compatibility/performance evidence, or DXIL conversion with Metal Shader Converter on the current released toolchain. 2. Use **GPTK 4** when the job is source-level porting to Metal 4, macOS 27/Xcode 27 beta tools are intentionally in scope, or agent-driven capture/debugging is valuable. 3. For GPTK 4, install or load Apple’s `game-porting-skills` plugin from `apple/game-porting-toolkit`. Do not copy its expert skills, milestone format, or `.porting/` artifacts into Socket. 4. Stop and request a decision when a project requires a beta toolchain but its shipping target must remain on stable tooling.

Evidence-First Porting

1. Inventory source API, build system, shaders, windowing, input, audio, assets, and existing platform layers. 2. Separate evaluation evidence from a native port commitment. A translated executable is a diagnostic baseline, not a shipped port. 3. For a GPTK 4 source port, let the upstream workflow own discovery, goal milestones, validation, and handoff artifacts. 4. Keep Socket-owned handoffs narrow: `game-controller-input-workflow`, `core-haptics-game-feedback-workflow`, `gamekit-game-center-workflow` when available, and native renderer or asset-streaming work. 5. Record toolkit version, OS/Xcode version, target hardware, launch configuration, trace or validation artifacts, and unresolved API or feature gaps. For D3D12, use the minimum checklist in `references/version-routing.md`: launch, graphics, input, audio, save, and network behavior; D3D12 feature use; shader-conversion failures; and one repeatable performance capture.

Boundaries

• Do not use GPTK to claim that a Windows game is compatible, performant, or releasable without actual evaluation evidence.
• Do not use the GPTK evaluation environment as a substitute for porting source code.
• Treat Apple’s upstream GPTK 4 skill plugin as an optional Git-backed dependency. Do not add it to Socket’s marketplace or make Socket releases depend on its install state.

Output

Return the chosen GPTK version, why it fits, prerequisites, the upstream skill/plugin action if needed, Socket handoffs, evidence required, and the next bounded porting step.