About this manual
This manual explains how to export a game made with ACTION GAME MAKER for iOS (iPhone / iPad) and run it on a simulator or a real device. It also covers what you need to prepare (a Mac, Xcode and an Apple account), the export settings, and things to watch out for when playing on an iPhone: screen size, notches and touch controls.
How iOS export works
Only apps that have been built and signed with Apple’s development tool Xcode can be installed on a device. Because of this, iOS export in ACTION GAME MAKER works as follows.
| Step | What you do | What you use |
|---|---|---|
| 1 | Export the game as an Xcode project | ACTION GAME MAKER |
| 2 | Open the Xcode project and set up signing | Xcode (Mac) |
| 3 | Run it on a simulator or a connected iPhone / iPad | Xcode (Mac) |
Steps 2 and 3 require a Mac. When you export with the Mac version of ACTION GAME MAKER, it can also create the distribution file (.ipa) as part of step 1 (see below).
What you need
| Item | Details |
|---|---|
| Mac | Needed to run Xcode |
| Xcode | Install it from the Mac App Store. If it asks you to install additional components (the iOS platform) the first time it starts, install them |
| Apple account | Needed to run on a real device (not needed for the simulator only) |
| iPhone / iPad | For testing on a real device. iOS 15.0 or later |
Apple accounts and the Team ID
An app installed on a real device must be signed by a team (a developer account).
- If you join the Apple Developer Program (paid), you can distribute on the App Store and send test builds through TestFlight.
- Even without joining, if you sign in to Xcode with your Apple ID, you can install the app on your own device with a personal team (Personal Team). In this case, the installed app stops launching after a certain period and needs to be installed again.
Exporting requires this team’s Team ID (10 letters and numbers). You can find it under “Membership details” on the Apple Developer website, or in “Signing & Capabilities” of a project in Xcode.
Creating the export settings
- In Maker mode, open the “Project” menu → “Export”.
- Choose “iOS” from “Add…”. The iOS settings (preset) are added to the list.
- Fill in the following settings on the right.
Required settings
| Setting | Details |
|---|---|
| Application → “App Store Team ID” | The Team ID you found above. Export is not possible while it is empty |
| Application → “Bundle Identifier” | A name that identifies the app. Use a string that will not clash with other apps, such as com.(your name or company).(game name). Letters, numbers, - and . can be used |
If something is missing or contains characters that cannot be used, the reason appears in red at the bottom of the export window.
Texture compression setting
Exporting for iOS requires “Import ETC2 ASTC” to be on in the project settings. When it is off, the export window shows “Target platform requires ‘ETC2/ASTC’ texture compression.”
- Press “Show Project Setting” next to the message.
- In the project settings that open, turn on “Import ETC2 ASTC”.
- When the images have finished reimporting, open “Export” again.
In projects with many images, reimporting can take a while.
Other main settings
| Setting | Details |
|---|---|
| Application → “Targeted Device Family” | The target devices. iPhone / iPad / iPhone & iPad (default) |
| Application → “Min iOS Version” | The lowest iOS version the game can run on. The default is 15.0, and it cannot be set lower |
| Application → “Short Version” / “Version” | The app’s version. If empty, the project’s version is used |
| Application → “Export Project Only” | When on, only the Xcode project is exported (see below) |
| Icons | Home screen icons and so on. If not set, the project’s icon is used |
| Storyboard | The image and background colour of the screen shown briefly at startup (launch screen) |
Exporting
- Select the iOS settings in the list and press “Export Project…”.
- Choose the destination folder and file name (
GameName.ipawhen “Export Project Only” is off,GameName.xcodeprojwhen it is on). Preparing an empty folder makes it easier to find the created files. - For testing, leave “Export With Debug” on. Turn it off when exporting for distribution.
- Save, and the export starts.
An Xcode project (GameName.xcodeproj) named after the game and a folder of its assets are created in the destination.
Exporting on a Mac (also creating the .ipa)
When “Export Project Only” is off, the Mac version automatically runs Xcode after exporting and goes on to create the distribution file (.ipa). This needs signing, so you must be signed in to Xcode with your Apple account.
If signing is not set up, it stops while creating the .ipa with “Failed to run xcodebuild with code (number)” or “Xcode project build failed”. The reliable way is to first turn on “Export Project Only”, export only the Xcode project, and run it from Xcode with the steps in the next section.
Exporting on Windows
The Windows version cannot create an .ipa. Export ends once the Xcode project has been created, and the note “.ipa can only be built on macOS.” appears. Copy the whole destination folder to a Mac and run it from Xcode with the steps in the next section.
Running in Xcode
- Double-click
GameName.xcodeprojin the destination to open it in Xcode. - Select the project at the top of the list on the left and open the “Signing & Capabilities” tab.
- Choose your team under “Team”. If “Automatically manage signing” is on, Xcode prepares what is needed for signing.
- In the run destination at the top of the window, choose a simulator (an iPhone model name) or an iPhone / iPad connected by USB.
- Press “
” (Run). The game is built and launched.
The first time you run on a real device, you may need to do the following on the iPhone / iPad.
- Turn on “Settings” → “Privacy & Security” → “Developer Mode” (a restart is required)
- In “Settings” → “General” → “VPN & Device Management”, “Trust” your developer account
About the simulator
The simulator reproduces an iPhone screen on your Mac. You can check how the screen looks and where the virtual pad sits even without a device at hand.
However, the simulator draws with a simplified method, so it runs more slowly than a real device. Check the speed of scenes with many objects on a real device.
Making the game playable on an iPhone
Touch controls (virtual pad)
ACTION GAME MAKER games are built to be played with a keyboard or gamepad. Exporting to iOS as is does not make them playable by touch (only mouse input conditions respond, to a one-finger touch).
To show buttons and sticks on the screen, use the “virtual pad”. It makes the game playable by touch without changing your existing visual script input conditions. See “Manual: Supporting touch controls with the virtual pad (virtual gamepad)” for how to set it up.
If the iPhone is connected to a gamepad, the game can be played without a virtual pad.
Screen size
An iPhone screen has a higher resolution than a PC window, and while the project setting “Stretch” stays disabled (the default), text looks small and more of the stage is shown. To scale the game up to fit the device screen, go to the project settings “Display” → “Window” → “Stretch” and set “Mode” to canvas_items and “Aspect” to expand or similar.
When more of the stage is shown, backgrounds such as the distant view may not reach the edge of the screen, and the background colour may show at the edge. In that case, increase the number of times the background repeats.
Cutouts (notch, Dynamic Island)
The game screen is drawn all the way under the notch and the Dynamic Island. On an iPhone held sideways, the left and right edges and the bottom edge of the screen may be hidden by the cutout or the home indicator.
- Do not place HUD elements such as the score right against the left or right edge of the screen; move them inward.
- The virtual pad is automatically placed inward, clear of the hidden areas.
Notes
- Running an iOS app requires a Mac and Xcode. Even if you export with the Windows version, the final build is done in Xcode on a Mac.
- Export is not possible while “App Store Team ID” or “Bundle Identifier” is empty.
- Export is not possible unless “Import ETC2 ASTC” is on. Turning it on reimports the images.
- Apps installed with a Personal Team (a free Apple ID) stop launching after a certain period. To keep testing, install it again from Xcode.
- Distributing on the App Store requires joining the Apple Developer Program and passing Apple’s review.
- Apps with the same “Bundle Identifier” overwrite each other on the device as the same app. When testing a different game, change the Bundle Identifier.