Speedrun your game port with agentic coding

Watch on Apple Developer

TL;DR

Agentic porting workflow in Game Porting Toolkit 4

Game Porting Toolkit 4 provides agentic skills for coding assistants: expert skills encode Apple-platform porting knowledge, while workflow skills impose a structured process. The porting assistant coordinates those skills so milestone work loads the relevant expertise automatically instead of relying on the model to choose the right context.

The demonstrated workflow ports Microsoft MiniEngine, a D3D12 open-source engine, to macOS using Claude Code. The same approach is described as applicable to larger projects, including adding Metal 4 alongside an existing Metal 3 backend in Godot.

• Discover: scan the codebase, capture reference output from the evaluation environment, and gather developer preferences.
• Plan: define porting goals and break the work into milestones small enough for agent sessions.
• Execute and Validate: implement milestone changes, then verify app launch, Metal API and shader validation, visual correctness, ground-truth comparisons, anti-pattern review, and memory issues.
• Skills preserve learned context across milestones so decisions and findings are not lost between sessions.

Install Game Porting Toolkit skills

Add the Game Porting Toolkit marketplace and install the skills plugin before invoking the porting assistant on a codebase.

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

Windowing, presentation, and frame pacing

The first milestone brings up a native window and a stable render loop before renderer work begins. Several skills work together: window creation and lifecycle, translating D3D12 swap-chain concepts to Metal, presenting drawables, and metal-cpp object lifetime patterns.

The goal is not just to show pixels; it is to avoid common blank-output, stutter, and frame-pacing failures before more complex rendering is added.

• Use Metal Display Link to drive the render loop.
• Handle lifecycle events such as focus changes and fullscreen transitions.
• Configure layer resolution and color space appropriately for games.
• Use direct-to-display presentation where appropriate for lower latency.
• Manage drawable lifetimes and resource residency to avoid stuttering and invalid GPU access.

Rendering with Metal 4

The Metal 4 renderer bring-up is split into GPU resources, shader pipelines, and command encoding. The skills bridge D3D12 engine assumptions to Metal 4's explicit memory management, shader binding model, and synchronization model.

For MiniEngine, the initial rendering goals include depth, shadow, and color passes, then SSAO and tone mapping, followed by dynamic lights using a compute-based light-culling pass. Validation compares GPU work against the evaluation environment before moving to later milestones.

• Register textures and other GPU resources in residency sets before use so the GPU can access them reliably.
• Use Metal Shader Converter runtime information instead of assuming D3D12-style descriptor layouts map directly to Metal argument buffers.
• Map D3D12 states to Metal 4 producer and consumer stages instead of relying on broad blanket barriers.
• Use shader reflection to detect parameter-count and layout mismatches that can silently shift bindings and break rendering.

Register resources for residency

Metal 4 resource access requires explicit residency management; skipping registration can compile but produce incorrect GPU results.

// With skill
residencySet->addAllocation(texture);
residencySet->commit();
// ...
argumentTable->setAddress(texture->gpuAddress(), bindPoint);

// Without skill
argumentTable->setAddress(texture->gpuAddress(), bindPoint);

Map D3D12 states to Metal 4 stages

The synchronization skill teaches the agent to translate D3D12 resource-state transitions into Metal 4's explicit producer-consumer barrier model.

// With skill
m_MtlPendingProducerStages |= MtlProducerStageFromD3D12(OldState);
m_MtlPendingConsumerStages |= MtlConsumerStageFromD3D12(NewState);
// ...
m_ComputeEncoder->barrierAfterStages(
    m_MtlPendingProducerStages,
    m_MtlPendingConsumerStages,
    MTL4::VisibilityOptionDevice);

// Without skill
m_ComputeEncoder->barrierAfterStages(
    MTL::StageDispatch,
    MTL::StageAll,
    MTL4::VisibilityOptionDevice);

Shader layout and reflection pitfalls

Several rendering bugs come from assuming that MiniEngine's D3D12 root-signature layout can be reused directly. The shader converter skills guide the agent to ask the Metal Shader Converter runtime for actual argument buffer offsets and reflected shader parameters.

These checks matter because layout mismatches may not produce immediate API errors; they can instead appear as incorrect lighting, shifted sampler tables, stretched textures, or other visual defects.

• Query argument buffer offsets from the Metal Shader Converter runtime rather than computing parameterIndex * descriptorSize.
• Reflect compiled shader objects to determine the actual parameter count used by the converted shader.
• Use reflection results to keep descriptor tables, sampler tables, and root-signature translations aligned with the shader.

Query argument buffer offsets

The Metal Shader Converter runtime owns the converted layout; hardcoded offset calculations can bind resources at the wrong locations.

// With skill
IRRootSignatureGetResourceLocations(m_MtlCurIRRootSig, locations);
size_t offset = locations[i].topLevelOffset;

// Without skill
size_t offset = paramIndex * descriptorSize;

Query shader reflection parameter count

Reflection avoids carrying over stale D3D12 root-parameter counts when the converted HLSL shader declares a different layout.

// With skill
IRShaderReflection* refl = IRShaderReflectionCreate();
IRObjectGetReflection(compiledObj, IRShaderStageCompute, refl);
// ...
s_RootSignature.Reset(4, 2); // Reflection reveals: 4 params

// Without skill
s_RootSignature.Reset(5, 2);

Autonomous GPU debugging with command-line tools

macOS 27 introduces command-line GPU debugging tools designed for agent workflows. gpucapture captures a GPU frame trace, and gpudebug inspects captures without requiring manual Xcode interaction.

In the MiniEngine port, the agent starts from visual symptoms, captures a trace, inspects resource bindings, constants, resource contents, pipeline data flow, dispatch calls, and dispatch dimensions, then compares against ground-truth captures to find and fix rendering issues.

• Use gpucapture while the app is running to collect a frame trace.
• Use gpudebug to inspect the trace similarly to GPU debugging in Xcode.
• Let validation compare pipelines, dispatch calls, dimensions, and other capture details against reference traces.
• Use the tools both for root-cause analysis and for milestone validation.

Game controllers and MetalFX integration

The game controller skill ports Windows input assumptions to the Game Controller framework. Instead of hardcoding an XInput-style fixed layout, the agent is guided to discover connected controllers, query supported controls, and handle connect and disconnect events dynamically.

MetalFX work is split into temporal upscaling and frame interpolation skills. The upscaling skill covers jitter in pixel space, motion-vector scale and conventions, MIP bias, and history reprojection. The frame interpolation skill covers a dedicated present thread, precise frame timing, and correct presentation order.

• Use GCController discovery and dynamic button-layout queries rather than fixed XInput mappings.
• Use MetalFX HUD overlays in macOS 27 to verify exposure, jitter sequence, and motion-vector scale behavior.
• Use HUD overrides for jitter multipliers and motion-vector scales to diagnose artifacts while the app is running.
• If HUD overrides fix the image, trace the fix back to the app logic that computes jitter or motion-vector values.

Related Sessions

• Go further with Metal 4 games

Unofficial, not associated with Apple. By