game-porting-toolkit

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 runtime. Covers offline/runtime DXIL compilation, root signatures, reflection output, ray tracing shaders, geometry/tessellation emulation compilation, framebuffer fetch in HLSL, programmable blending in HLSL, Metal_HLSL.inc, and compatibility flags. Do NOT trigger for binding compiled shaders to encoders — use integrating-metal-shaderconverter-shaders for that.

ALWAYS use when creating Metal pipeline state objects with Metal 4 descriptors (MTL4RenderPipelineDescriptor, MTL4ComputePipelineDescriptor, MTL4MeshRenderPipelineDescriptor) via MTL4Compiler. Covers function descriptors, function constant specialization, flexible/unspecialized PSOs, color-attachment mapping, async compilation (MTL4CompilerTask), pipeline caching (MTL4Archive, MTL4PipelineDataSetSerializer), static/binary shader linking, and pipeline reflection. Do NOT trigger for HLSL/DXIL → metallib — use compiling-with-metal-shaderconverter.

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 colors, gamma/sRGB problems, texture artifacts, z-fighting, alpha blending, flickering, visual corruption, and upside-down/mirrored geometry. Works with or without a GPU trace. Do NOT trigger when the user just wants to inspect an existing .gputrace.

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, static samplers, bindless resources, vertex fetch, separate stage-in, geometry/tessellation emulation, compute dispatch, unbounded arrays, and append/consume buffers. Do NOT trigger for compiling DXIL/HLSL to metallib — use compiling-with-metal-shaderconverter for that.

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 ownership, bridge casts at ARC/metal-cpp boundaries, or any question about when and how Metal objects are retained, released, or destroyed.

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 deferred destruction. Trigger for MTLBuffer, MTLTexture, MTLHeap, MTLResidencySet, addAllocation, requestResidency, useResidencySet, addResidencySet, MTLStorageMode*, MTLPurgeableState, MTLTextureViewPool, MTLResourceViewPool, newTextureViewWithPixelFormat:, copyFromBuffer:toTexture:, "GPU fault on resource", "non-resident resource", heap aliasing. Do NOT trigger for TBDR architecture or Metal 3 → Metal 4 namespace tables — use `translating-to-metal4-api`. Barrier visibility / `MTL4VisibilityOption*` / render-pass transition barriers — use `managing-metal4-synchronization`. `CAMetalLayer.residencySet` — use `presenting-metal-drawables`. `NS::SharedPtr` / autorelease pool / ARC bridging — use `managing-metal-cpp-lifetimes`.

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 barrier-related visual corruption.

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.

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.

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.

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.

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.

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.

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 flow verification. Can also be run mid-milestone.

ALWAYS use when implementing or debugging the Metal drawable presentation contract — `CAMetalLayer` configuration, drawable lifecycle (`nextDrawable`, `waitForDrawable`, `signalDrawable`, `present`), vsync (`displaySyncEnabled`), `CAMetalDisplayLink`, HDR/EDR layer setup, direct-to-display vs composited, or drawable-residency-set rules. Trigger for CAMetalLayer, CAMetalDrawable, nextDrawable, signalDrawable, waitForDrawable, displaySyncEnabled, presentAfterMinimumDuration, drawableSize, framebufferOnly, wantsExtendedDynamicRangeContent, EDR headroom, ProMotion, swap chain port, "blank window", "vsync not working". Do NOT trigger for render-thread / run-loop / resize / fullscreen integration on macOS — use `setting-up-macos-window`. General `MTLResidencySet` semantics — use `managing-metal4-resources`. Cross-API translation tables for non-presentation APIs — use `translating-to-metal4-api`. For dual-frame presentation via a present thread — use `using-metalfx-frame-interpolation`.

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 notifications routed into the engine via `Engine*` callbacks, keyboard/mouse input replacing WndProc, fullscreen transitions, cursor visibility and mouse-look confinement, sleep prevention, and per-frame screen state for sizes and EDR. Use whenever the question touches porting a Windows game window to macOS — AppDelegate / GameView / GameViewController setup, replacing WndProc, fullscreen, cursor handling, window resize, or AppKit notification routing.

ALWAYS use as the Metal 4 API reference and cross-API translation map when porting graphics code to Metal 4 — translating Metal 3, D3D12, or Vulkan calls, looking up any MTL4 / Metal 4 API or renamed type, finding the Metal 4 equivalent of a source-API call, or learning what the redesign removed or changed. Covers the Metal 3 → Metal 4 namespace/type table, removed/changed APIs (ParallelRenderEncoder, set*Bytes), Apple GPU TBDR (tile-based deferred rendering) architecture, and the D3D12 / Vulkan / Metal 3 → Metal 4 translation tables. Do NOT trigger for buffer/texture/heap/residency/storage-mode management — use `managing-metal4-resources`; barriers, fences, or events — use `managing-metal4-synchronization`; pipeline state creation, MTL4Compiler, or reflection — use `creating-metal4-shader-pipelines`; CAMetalLayer drawable presentation — use `presenting-metal-drawables`.

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 GCController API or GameController framework (controller lifecycle, connect/disconnect, current controller, player index, profile-based input, modern input API, polling, callbacks, haptics, rumble, adaptive triggers, motion/IMU, or on-screen controls), or when porting Windows controller code such as XInput, DirectInput, GameInput, RawInput, joystickapi.h, IOKit HID, IOHIDManager, or HidP_* APIs. Do NOT trigger for keyboard or mouse input.

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, use gpucapture, capture from the command line, do a Metal frame capture, ask how to capture a Metal trace, capture a running process, or otherwise create a .gputrace file from a Metal app. Do NOT trigger when the user already has a GPU trace and wants to analyze or diagnose it — use using-gpudebug for that.

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, textures/buffers, and shader source. Also trigger when another skill needs to read data from a .gputrace (fetch textures, inspect state, list encoders). Do NOT trigger for capturing a new trace — use using-gpucapture.

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 load/store-action visual indicators. Trigger when working with Metal validation (MTL_DEBUG_LAYER, MTL_SHADER_VALIDATION, the validation layer, API validation, MTL_DEBUG_LAYER_VALIDATE_LOAD_ACTIONS, MTL_DEBUG_LAYER_VALIDATE_STORE_ACTIONS, per-pipeline validation, MTL4PipelineOptions.shaderValidation, validation perf hit), or when encountering symptoms like shader validation errors not appearing, fuchsia color render artifacts, the red/white checkerboard, or zerofill output. Do NOT trigger for general rendering bug diagnosis where validation isn't the relevant tool.

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 the framerate, or mentions MTLFXFrameInterpolator (Metal 3) or MTL4FXFrameInterpolator (Metal 4). This skill assumes temporal upscaling is already integrated (use using-metalfx-temporal-upscaler first if not). Also trigger when the user says "add frame gen", "120fps", "interpolate frames", or wants smoother motion.

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", "add DLSS-like upscaling", "add FSR-like upscaling", TAA, motion vectors, jitter pattern, or mention MTLFXTemporalScaler (Metal 3) or MTL4FXTemporalScaler (Metal 4) directly.