Building with Xcode

Homebrew is fine and good, but for macOS, building with Xcode is preferred. It is also the only way to build universal binaries at the moment. The only prerequisites here are downloading the current or older version of Xcode, and installing Homebrew.

Setting Up Command Line Tools

After Xcode has been installed, open the settings through either the menu bar or the ⌘+, keyboard shortcut.

Move to the Locations tab, set Derived Data to "Relative" (this isn't necessary, but it makes the build result easier to find), and set Command Line Tools to your current version of Xcode.

Setting Up the Repository

Now, to clone the repository, open up your terminal and run:

cd $HOME/Documents
git clone https://gitlab.com/mkxp-z/mkxp-z --recursive $HOME/Documents/mkxp-z
cd $HOME/Documents/mkxp-z/macos/Dependencies

brew bundle

If you intend to integrate your game with Steam, you will first need to:

1. Download Steamworks.

2. Move the sdk folder contained inside to macos/Dependencies/Frameworks/steam within the repository's folder.

3. That's it. Make sure it's done before you run setup.command in a minute. If you already have, you can just run it again.

Building mkxp-z

When debugging through Xcode (or when mkxp-z is launched with the MKXPZ_SELECT_PATH environment variable is set to 1), you will be asked to select a path pointing to the location of the game you want to launch.

Normally, however, relevant game files must be placed within Contents/Game within mkxp-z's application bundle, unless it has been set otherwise within the json configuration.

Debugging

Cool, now you've got all that done, the rest is pretty simple. The repository has been downloaded to your Documents folder, so you can either go there yourself, or type this last thing into the terminal: open ~/Documents/mkxp-z.

Navigate to macos and open setup.command by double clicking it. It will build all the dependencies that mkxp-z needs to run, and might take a while.

Once it's done, open the Xcode project, and open the Schemes menu in the title bar.

Select the scheme that is most relevant to you.

Select the scheme that is most relevant to you. This is probably either the Universal or Universal (Steam) scheme. If the version of Xcode you are using is older than 12, you must use either the Intel or Intel (Steam) scheme. (Building the Universal Steam scheme requires a version of Steamworks >= 1.52). You should also make sure that My Mac is selected as the build target; debugging might not work otherwise.

Now, you can build the app by clicking the debug icon on either Xcode's sidebar, or your Touch Bar (if you have one).

If you set your DerivedData location to relative, you can find the build results in the same folder as the Xcode project.

Setting Your Steam App ID

If you are building with Steamworks integration, mkxp-z will look for steam_appid.txt within the Contents/Resources subfolder of the bundle. If you would like to have the app use SteamAPI_RestartAppIfNecessary rather than the default behavior, set STEAM_APP_ID in macos/config/steam/steamshim.xcconfig.

Distribution

mkxp-z must be built in Debug mode, otherwise ANGLE will break and no display will be shown in the game's window. Therefore, all you need to do is change your build target from My Mac to Any Mac, then build the application with Command+B. The result can found in DerivedData within the repository's macos subdirectory if you set the build directory to relative. If not, you can choose Product > Show Build Folder in Finder from the menu bar.