AGS engine Mac OS X port

[Crimson Wizard]

The old forum thread may still be found here. Please beware that it was started many years ago and may contain alot of outdated information.

This new thread is dedicated to discussing the Mac OSX port of AGS engine. Following is a brief cover of the topic.

NOTE: I used information provided by @eri0o in other forum threads to write the following, but I am not a Mac developer myself, so the instructions below may contain gaps or mistakes. If you notice anything wrong or missing, then please report that in comments.


AGS engine runs natively on 32-bit and 64-bit Mac OSX.
To run AGS games on Mac at the very least you need the Mac engine executable and a game data.

In general, there are two ways to prepare a game for Mac: a "proper" and "quick and dirty" ones.

A proper way is to create a Application Bundle: which is a package containing game data compiled by the editor (gamename.ags and any other custom files), engine executable, and additional files required by the Mac. The Bundle may also be signed and notarized. This is the way to officially distribute your game for Mac, whether commercially or for free.

A "quick and dirty" way may be used whenever you need a quick test of your game. This method requires simply a engine executable and game data files, placed together in a single folder. Running engine exe will make it look for a nearby game data, load and run it. The same method could be used to run virtually any game made in AGS, even if it was not released for Mac.

We discuss this in more detail further.


Building games for Mac OSX in the Editor

Unfortunately, at the time of writing this post, AGS Editor does not support preparing a Application Bundle for Mac. This may change in the future, in which case this section will be updated.

For now, you have to build your game normally, and then find the files located inside Compiled/Data folder. These are "raw game data" files, independent from any operating system. You should be using these when preparing a Mac package yourself.


Making a Application Bundle

Let's talk about the proper way of preparing your game for Mac, that is - creating Application Bundle.

In macOS, a bundle is a directory with a standard hierarchical structure that contains executable and resources.
Here's the Apple technical documentation regarding this:  Application Bundle. It may be not trivial to understand for a non-technical user at the first attempt, but I recommend getting acquainted with it nevertheless.

At minimum, your ags game application bundle will look like this:

Code: ags

📁 MyGame.app/
  📁 Contents/
      📜 Info.plist
      📁 MacOS/
        ☕ ags
      📁 Resources/
        📦 mygame.ags

At the top level we have a directory that has a name that ends in .app, e.g. "MyGame.app".
Below there's a subdirectory called Contents. This is where you place the bundle files, some of them in further subdirectories.

1. Info.plist

Info.plist - this is a runtime-configuration file called the "information property list". This file is a plain-text xml file, which contains information required for the Mac to handle your app bundle correctly.
You may find an example of this file in our engine repository:
https://github.com/adventuregamestudio/ags/blob/master/OSX/xcode/AGSKit/AGSKit/Info.plist
This file may be used as a template for the plist in your bundle.

If you look inside, you will see a series of <key> and <string> entries. These are like "property name" and "property value". You may edit values (inside <string> entry), but should not touch the "keys" unless you know what are you doing. You may also add more key/value entries if necessary.
Related Apple docs:
- Application Bundle
- About Info.plist Keys and Values


The most important entry there is CFBundleExecutable. You must enter the value for this entry, which is the plain name of the engine executable (without any paths). Usually that should be ags, for example:

Code: ags

<key>CFBundleExecutable</key>
<string>ags</string>

2. MacOS directory

This directory must contain the engine executable (called plainly "ags" or similar).

3. Resources

This directory must contain all the game resources: these are the files that you normally distribute as "AGS game" (except ".exe" file, of course): gamename.ags, audio.vox, speech.vox, acsetup.cfg, translation files, and so on. In the usual case you should just copy contents of Compiled/Data folder there.

Signing and Notarization

In theory you may skip this, but if you do then whenever a player tries to run your game, they would have to go through a number of steps to allow this game to run on their Mac computer. So ideally you should Sign and Notarize your game before distributing. You will need an Apple developer account for this.

Here's a Apple doc on this topic:
https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution

KNOWN ISSUES

If you have prepared the Application Bundle on Windows, there will be a problem that the engine executable will not be marked as "executable" for Mac, and won't be run. If that's the case, then you can fix it on Mac using "chmod" command from the terminal:

Code: bash

chmod +x ags

This mark can be then preserved if you distribute your bundle using archive type that keeps it: such as "dmg" or "tar.gz". There's also an information that Steam may take care of this, but this has to be double checked.


Getting the Mac engine

NOTE: this section is currently underway, we will need to gather more information on this.

There are obviously 3 ways you can get the AGS engine for Mac:
1. Build it yourself, from the source code in our repository. You shall have Mac computer with Xcode IDE installed for this. This is explained in this readme: https://github.com/adventuregamestudio/ags/blob/master/OSX/README.md
2. Get it from someone else who built it. Please note that the built executable will only be compatible with a certain range of OS versions.
3. We might provide the Mac port executable in our AGS releases, but if we do, then these likely will only be guaranteed to work on the recent versions of Mac OS.


Game-written paths and files

Following are the default locations of files created by the game:

User config: Users/<username>/Library/Application Support/GAMENAME/acsetup.cfg
Game saves: Users/<username>/Library/Application Support/GAMENAME/
Shared game files*: Users/<username>/Library/Application Support/uk.co.adventuregamestudio/GAMENAME/
Engine log location: Users/<username>/Library/Application Support/uk.co.adventuregamestudio/

* - shared game files are ones that are written in script using $APPDATADIR$ path token.

NOTES:
1. You, or players, may assign a different savegame location in game config, see these docs:
https://adventuregamestudio.github.io/ags-manual/DefaultSetup.html#environment
https://adventuregamestudio.github.io/ags-manual/EngineConfigFile.html#configuration-file-options
2. Because there's no analogue of WinSetup on Mac, the "user config" may only be written by the engine if you call System.SaveConfigToFile() in script.