game-porting-skills

Game Porting Toolkit

🔗 Jump to: Overview · Feedback · Getting started · Skills · Samples · License

Overview

The Game Porting Toolkit helps developers bring existing games and engines to Apple platforms, providing developer tools such as the evaluation environment for Windows games and Metal Shader Converter. To learn more, go to https://developer.apple.com/games/game-porting-toolkit/.

This repository includes:

• A collection of agent skills to assist porting games to Apple platforms so you can produce higher-quality ports and ship on Apple platforms faster.

  • Expert skills that provide domain knowledge to AI agents - covering Metal 4, MetalFX, shader compilation, platform frameworks, and debugging tools.
  • Workflow skills that provide a streamlined, milestone-based porting process, pulling in expert skills and persisting state between sessions.

• Metal-cpp, enabling the use of Metal directly from C++.

• Code samples covering end-to-end porting techniques.

Feedback

We would love to hear your feedback using the Apple Feedback Assistant. Select feedback for Developer Tools, and choose the Game Porting Toolkit sub-category. We aren't accepting pull requests on this repository at this time.

Getting started

Prerequisites

• A Mac with Apple silicon.
• macOS 27 — provides new Metal debugging tools — gpucapture and gpudebug — to streamline the debugging process.
• Xcode 27 — enables the latest agent-based workflows, equipped with MCP tools for Xcode and lldb.
• Game Porting Toolkit 4 - provides latest versions of the evaluation environment for Windows games and Metal Shader Converter.

Installation

Clone with submodules so metal-cpp is populated:

git clone --recurse-submodules https://github.com/apple/game-porting-toolkit.git

If you already cloned without it, run:

git submodule update --init --recursive

Installing the skills

Installation differs depending on your coding agent of choice.

Claude Code

• Register the marketplace:

  /plugin marketplace add apple/game-porting-toolkit
  

• Alternatively, register the marketplace from the local git checkout:

  /plugin marketplace add /path/to/game-porting-toolkit
  

• Install the plugin:

  /plugin install game-porting-skills@game-porting-toolkit
  

Codex CLI

• Register the marketplace:

  codex plugin marketplace add https://github.com/apple/game-porting-toolkit
  

• Alternatively, register the marketplace from the local git checkout:

  codex plugin marketplace add /path/to/game-porting-toolkit
  

• Install the plugin:

  codex plugin add game-porting-skills@game-porting-toolkit
  

Gemini CLI

Install the extension from a local directory:

gemini extensions install /path/to/game-porting-toolkit/game-porting-skills

Porting with the workflow skills

The workflow skills run a port as a resumable project, built on two levels: a goal spans many sessions ("get the simplest sample rendering"); a milestone is one session of bounded work toward it. porting-methodology is always loaded and defines the rules; the rest are steps you invoke, directly or through the porting-assistant agent.

1. Discover (porting-discover) — analyze the codebase; write a discovery report. Once per codebase.
2. Plan a goal (porting-plan-goal) — pick the simplest target; break it into dependency-ordered milestones.
3. Run each milestone through four user-gated phases:
   • Prepare (porting-start-milestone) — study code, load skills. No code yet.
   • Execute (porting-execute) — write code to the engine's conventions.
   • Validate (porting-validate) — verify at runtime: GPU capture, validation layers, leak checks, review.
   • Handoff (porting-handoff) — commit, update memory, write a handoff note.
4. Repeat — plan the next goal until the port is done. porting-status reports where things stand, any time.

State lives on disk in .porting/ (discovery report, goal documents, handoff notes, porting-memory.md), so a port survives session boundaries and context resets.

For the full list of expert and workflow skills, see game-porting-skills/README.md.

Samples

Starting a Game Port with Metal