Apple Game Porting Skills

Metal 4 explicit synchronization - barriers, fences, events, and cross-API state translation (from D3D12, Vulkan, OpenGL). Use when porting GPU synchronization, translating resource state transitions, or debugging…

ALWAYS use when working with Metal 4 resources - buffer / texture / heap creation, storage modes, `MTLResidencySet` management, heap aliasing, purgeable state, texture view pools, GPU lossless compression, and…

ALWAYS use when creating Metal pipeline state objects with Metal 4 descriptors (MTL4RenderPipelineDescriptor, MTL4ComputePipelineDescriptor, MTL4MeshRenderPipelineDescriptor) via MTL4Compiler. Covers function…

ALWAYS use when implementing or debugging the Metal drawable presentation contract - `CAMetalLayer` configuration, drawable lifecycle (`nextDrawable`, `waitForDrawable`, `signalDrawable`, `present`), vsync…

ALWAYS use when writing or porting Metal object lifetime management code in metal-cpp - including crashes on release, use-after-free, memory leaks, autorelease pool placement, NS::TransferPtr vs NS::RetainPtr…

ALWAYS use when integrating Metal shader converter (commonly referred to as MSC) shaders at runtime - binding model, top-level argument buffer (TLAB), root signature resource locations, descriptor/sampler heaps,…

ALWAYS use when compiling DXIL/HLSL to metallib with Metal shader converter (commonly referred to as MSC) via the metal-shaderconverter CLI or libmetalirconverter (IRCompiler, IRObject, IRShaderReflection) at…

ALWAYS use when the user wants to add MetalFX temporal upscaling, super-resolution, or upscaling to a Metal app - whether they say "add MetalFX", "add temporal upscaling", "render at lower resolution and upscale",…

ALWAYS use to add MetalFX frame interpolation with a dedicated PresentThread for precise dual-frame presentation to a Metal app. Use this skill when the user wants to add frame interpolation, frame generation, double…

Setting up the macOS window layer when porting a Windows game to Metal. Covers AppDelegate + NSWindow programmatic setup, a CAMetalLayer-backed GameView with CAMetalDisplayLink, GameViewController lifecycle, AppKit…

ALWAYS use when the user has any question about game controller input on Apple platforms - whether writing new code, porting from Windows, or modernizing an existing implementation. Trigger when working with the…

ALWAYS use when a user wants to enable, configure, or run Metal validation - API validation (MTL_DEBUG_LAYER) for CPU-side API misuse, shader validation (MTL_SHADER_VALIDATION) for GPU-side memory errors, or the…

ALWAYS use when a user wants to capture a GPU trace (.gputrace) of a Metal application. Trigger when the user wants to capture a GPU trace, get a gputrace, record a Metal frame, capture a frame, capture GPU workload,…

ALWAYS use when a user has a .gputrace file and needs to inspect, navigate, or extract resources from it using the gpudebug CLI. Covers draw calls, render encoders, pipeline state, resource bindings,…

ALWAYS use when a user porting a game to Metal reports a rendering issue - blank screen, wrong output, or anything that looks incorrect on Metal vs. the source platform. Covers black screen, missing geometry, wrong…

Core development methodology for porting games and engines to Apple platforms. Defines porting goals, milestone lifecycle, debugging escalation, and conventions. Preloaded by the porting agent.

Analyze a codebase before starting a Metal 4 port. Produces a discovery report with platform readiness, graphics backend analysis, feature coverage matrix, and trace-grounded findings. Use before any porting work begins.

Define the next porting goal. Reads the discovery report and current porting state, proposes a goal with milestones, and creates a goal document.

Begin the next milestone. Reads the goal document and latest handoff note, loads relevant skills, studies code paths, and produces a preparation summary for user review. Does NOT write code.

Begin writing code for the current milestone. This is the explicit go-signal after /porting-start-milestone preparation has been reviewed and approved by the user.

Run the validation checklist before the milestone's final commit. Checks runtime verification, visual correctness, reference artifact comparison, Metal validation, memory leaks, skill-driven code review, and data…

Close out the current milestone. Prompts the user to commit, updates porting-memory.md (watch list and feature status), writes a handoff note, updates the goal document milestone status, and requests a context reset.

Show the current porting status. Reads the goal document, porting-memory.md, and latest handoff note to report where things stand. Read-only - does not continue any work.