How Apple's Game Porting Skills help move Windows games to Mac
If you have the source for a Windows game and want a Mac version, Apple's Game Porting Skills help a coding assistant break the port into verifiable stages. This guide covers choosing tools and a first scene, then gathering evidence from the first successful build through release readiness.

What is game porting?
Porting means adapting a game for another system, such as moving a Windows game to macOS or adapting it for iPhone and iPad. The work can include moving graphics from DirectX to Metal, adapting audio and controls, and handling windows, screen sizes, full-screen mode, and resources.
Think of an appliance built for a different socket. You have to adapt how it connects and check that it works in the new setting. Running a Windows binary on a Mac can help assess compatibility. A native macOS version takes project changes and checks for rendering, controls, and performance.
What are Game Porting Skills?
Apple publishes Game Porting Skills in the Game Porting Toolkit 4 repository. A skill is a guide to a specific task, such as finding out why a scene renders incorrectly. The coding assistant reads the project, analyzes code, suggests changes, and runs tools with the permissions you give it. A developer needs access to a project they can use and modify before starting a port.
How the Toolkit, skills, and compatibility tools differ
| Tool | What it does | When to use it |
|---|---|---|
| CrossOver | Runs some existing Windows games on Mac. Compatibility depends on the game. | You want to play. Check for an official Mac version first. |
| Game Porting Toolkit | Evaluates a Windows game binary on Apple silicon and provides tools to convert shaders or inspect graphics. | You need a baseline before porting or are adapting the project. |
| Game Porting Skills | Gives a coding assistant Metal guidance and a porting workflow. | You can modify the project and want AI assistance at each stage. |
| Coding assistant | Reads files, runs tools, and edits code within its permissions. | You want to apply the skills to a real project. |
Choose based on what you want to do
| Your goal | How to begin | Reason |
|---|---|---|
| Play a Windows game on Mac | Check for an official Mac version, then look up CrossOver compatibility. | You are working with the existing game files. |
| Assess a game before deciding to port | Try the Windows binary in the Toolkit's evaluation environment. | It gives you an initial view of compatibility and performance. |
| Build a Mac version from source | Use the Toolkit with a coding assistant that has the skills installed. | You will need to change several systems and verify them one at a time. |
| The game already uses a cross-platform engine | Check the engine's build and export support first. Use the skills where you get stuck. | The engine may handle part of the work for you. |
| You only have someone else's game installer | Look for a way to play that the game's owner supports. | You need separate rights to modify or distribute the game. |
CodeWeavers' CrossOver uses a compatibility layer to run Windows programs on Mac. Results vary by game. Apple's evaluation environment helps you gather information before porting. Release readiness depends on testing the port itself.
- Players can start by checking for a Mac version and looking up compatibility.
- If you are learning about AI, read the Workflow Skills and watch Apple's demo to see the steps in practice.
- If you have the source, evaluate the game and pick a small, testable goal before asking the assistant to change code.
When to use Expert Skills and Workflow Skills
Expert Skills provide technical guidance, such as how to map D3D12 calls to Metal 4, manage buffers and textures, or inspect a frame with incorrect colors using Metal tools. Workflow Skills break the port into stages so the team knows when to apply that guidance and how to verify the work before handing it off.
Apple's Expert Skills cover Metal 4, converting shaders (programs the GPU uses to process graphics), controller support, image processing with MetalFX, and debugging symptoms like black frames or incorrect colors.
- Discover: Inspect the code and Windows dependencies, then record project constraints.
- Plan: Pick the first verifiable goal and order milestones by dependency.
- Prepare: Read the files, select the relevant Expert Skills, and agree on what to verify.
- Execute: Keep code changes within the milestone.
- Validate: Build, run, and gather evidence against the agreed criteria.
- Handoff: Record the results, open issues, and next step for whoever takes over.
Apple repeats Prepare through Handoff for each milestone. The discovery report, goals, and handoff notes live in .porting/, so another session or teammate can pick up the work.
Inspect the code and pick the first scene to port
Suppose the team has the source for a DirectX game and a test scene that draws one object. Pick that scene first to isolate rendering from audio, menus, and saving. Capture a reference image from the original game before changing the code.
- Inspect rendering, input, audio, and shaders for Windows dependencies.
- Pick the first goal, such as opening a game window and drawing one object on Mac.
- Have the assistant propose how to set up the project, create the window, and adapt rendering. Split the plan into milestones you can verify.
- Change one subsystem at a time and have a developer review consequential edits.
- Build and test on real hardware. Compare the image and exercise the controls when those parts are ready.
- Once the first scene passes, move on to input, audio, and performance for each target device.
A first prompt for inspecting the project
Inspect only this Windows game's rendering system to prepare a Mac port. Leave the files as they are. Identify the files that call DirectX, the parts we can reuse, and any risks you are unsure about. Propose a first scene small enough to build, run, and compare with the original.
Before allowing edits, open the files the assistant cites and check that they match the game's actual execution path. If the first plan changes graphics, input, and audio together, split it until you can verify each change separately.
| Possible issue | How the assistant can help | What the team must verify |
|---|---|---|
| DirectX calls are tied to resource creation. | Locate buffer and texture creation and propose a Metal approach. | The game builds and runs on Mac, and draw calls receive the expected resources. |
| The original shader uses a platform-specific format. | Interpret converter errors and suggest shader changes. | Compare the rendered image with the reference after conversion. |
| Shader conversion succeeds, but surfaces disappear or colors are wrong. | Suggest hypotheses and pick a frame for GPU capture. | Compare the same frame with the original, inspect the draw call, and rerun the test. |
| Controller or mouse behavior changes. | Find the code tied to Windows input APIs. | Navigate menus, play, and switch physical input devices. |
| The game opens but stutters or uses too much memory. | Suggest what to measure and which Metal profiling tools to use. | Measure the same gameplay segment on the target hardware against the team's criteria. |
This is a hypothetical KrobClick example. For a developer demonstration, the WWDC session in the sources shows Apple's workflow with Microsoft MiniEngine.
What to prepare before installing
| What you need | What it is for |
|---|---|
| Apple silicon Mac | Evaluate and test the game as described in Apple's guide. |
| macOS 27 | Provides Metal debugging tools such as gpucapture and gpudebug. |
| Xcode 27 | Build and debug apps for Apple platforms. |
| Game Porting Toolkit 4 | Evaluate Windows binaries and use the shader conversion tools. |
| Coding assistant that supports the skills | Read and edit the project within the permissions you set. |
| Project you are authorized to modify | Access the source and assets the port requires. |
You can read the guide and watch the demo without a Mac or a project. A real port requires reading code, using a terminal, and checking changes. Graphics fundamentals help when the assistant misdiagnoses a problem or cannot fix it.
Install Game Porting Skills for Claude Code, Codex, or Gemini CLI
Start with Apple's repository
The apple/game-porting-toolkit repository contains the skills, sample code, and metal-cpp for using Metal from C++. Read the README for your version and follow the instructions for the assistant you use.
Install in Claude Code
Enter these two commands in Claude Code.
/plugin marketplace add apple/game-porting-toolkit
/plugin install game-porting-skills@game-porting-toolkit
Install in Codex CLI
Open a terminal with Codex CLI available, add the marketplace, and install the skills.
codex plugin marketplace add https://github.com/apple/game-porting-toolkit
codex plugin add game-porting-skills@game-porting-toolkit
Install in Gemini CLI
Clone the repository with its submodules, then replace the example path with the actual folder on your machine.
git clone --recurse-submodules https://github.com/apple/game-porting-toolkit.git
gemini extensions install /path/to/game-porting-toolkit/game-porting-skills
Choose the instructions for the assistant you use. KrobClick checked the commands against Apple's README. We have yet to run the installation ourselves. Check the guide for your version if the commands differ from what you see.
Inspect the project and verify the result yourself
Inspect this game project for a possible macOS port. Leave the files unchanged. Identify the systems that need changes, likely problems, and milestones we can test one at a time.
Review the report and approve the plan before edits begin. After the changes, check the build, open the game, test visuals and input, and compare the evidence with the agreed goal.
Six checks before calling the port complete
Decide before you start whether this milestone ends with the first rendered scene or with a release-ready game. This KrobClick checklist is a starting point you can adapt.
| Readiness stage | Pass criteria | Evidence |
|---|---|---|
| 1. Builds | Produces an app for the target machine. | Command, tool versions, and build log. |
| 2. Launches | Repeated launches reach the intended scene. | Launch log and capture from the target machine. |
| 3. Renders correctly | Objects, lighting, and key visuals match the reference to the team's standard. | Comparison images and a GPU capture when needed. |
| 4. Controls work and gameplay is playable | Menus, key controls, and a short gameplay loop work with supported devices. | Input test results by device. |
| 5. Runs reliably | Sustained and repeated play meets the team's time and resource criteria. | Error logs, memory use, and repeat test results. |
| 6. Ready for players | Performance, settings, devices, and release steps meet the target requirements. | Results on real devices and the team's acceptance checklist. |
A sample handoff after porting the first scene
This fictional handoff is a template a team can adapt.
- Goal: Open a window and render one test scene on Mac.
- Changes: Record the files changed, why they changed, and which graphics code now uses Metal.
- Results and evidence: The build passed and the scene opened. Attach the build log and comparison images from both versions.
- Open issues: Lighting still differs from the reference, and controller input and audio have yet to be tested.
- Next step: Capture the same scene on the GPU to investigate the lighting difference, then rerun the test.
Where Game Porting Skills help and where they fall short
Teams can use the skills to break a port into stages they can verify. The assistant can consult guidance on Metal, shaders, and debugging, and the team can reuse the discovery, planning, and verification steps for later milestones. Developers new to porting can use the assistant's plan as a starting point for learning.
An assistant's changes can break the build, render incorrectly, or affect another part of the game. The workload depends on the engine, libraries, graphics stack, and Windows dependencies. Mac testing and checking touch controls and performance on an iPhone or iPad are separate jobs.
Common questions before porting
Can I use the skills to play Windows games on Mac?
The skills guide development work. To try running a Windows game binary, look at a compatibility tool or the Toolkit's evaluation environment, depending on your goal.
Can someone who has never coded get started?
You can watch the demo and read the workflow to understand how AI fits in. Changing a real project takes someone who can read the code and verify results on the target machine.
Do I have to use Claude Code?
Apple provides instructions for Claude Code, Codex CLI, and Gemini CLI. Check the commands for the version you installed.
How can I tell that the skills are from Apple?
Start from Apple Developer or the apple/game-porting-toolkit GitHub repository. Both point to the skills Apple maintains.
Are Game Porting Skills free?
Apple makes the repository available under Apache-2.0. AI assistants, supporting services, hardware, and developer accounts may have their own terms or costs.
If the Mac build passes, does that cover iPhone and iPad?
Use the same checklist as a starting point, then add touch controls, layout, and performance checks on the target devices. Mac results cover the environment you tested.
Where do I start if I only have the purchased game files?
Check for an official Mac version or compatibility information for tools that run the existing game. To build a new version using this workflow, first get access to the project and check your rights to modify and distribute it.
Rights and costs
The Apple repository's Apache-2.0 license covers its code under that license's terms. Your game's code, music, artwork, and libraries have their own terms. Check your rights to modify and distribute them before use. Check AI tools, hardware, and developer account costs separately.
KrobClick's view: Review the evidence before closing the milestone
Apple separates Expert Skills for technical questions from Workflow Skills for tracking goals. Validate and Handoff preserve results across sessions. For KrobClick, the practical benefit is that a team can compare the assistant's answer with build logs, captures from the running game, and test results. If the assistant misreads the code or skips the target hardware, the milestone still needs verification.
If you are learning about AI, read how a domain guide changes what an existing assistant can do. If you are developing a game, choose a small scene and agree on the evidence before starting. If you want to play, start with a Mac version or compatibility information.
Sources
- Apple Developer — Game Porting Toolkit
- Apple: Source code, setup, and porting workflow
- Apple: Expert Skills and Workflow Skills reference
- WWDC26 — Speedrun your game port with agentic coding
- CodeWeavers: CrossOver Mac user guide
- Apple — Bring your game to Mac, Part 1
This article draws on Apple's documentation. The test scene is hypothetical and illustrates how to verify the work.