Messages

I've put a big post in the engine forum below about how I updated 3.3.3 to work on iOS. It serves as a complete guide to releasing an AGS game on iPhone or iPad. I didn't want it to get lost in this biiiiig thread so I made a new thread :-)

How to release an AGS game on iOS
---------------------------------

Hi, this is Janet from Wadjet Eye. I keep getting people asking how to release commercial AGS games on iOS, so I thought I'd write a full account, from start to finish. You can follow this (with reference to my fork of the engine) or you can just fork my fork (easier.)

Overview
--------

When I first released an AGS game on iOS, I based it on JJS's (Jochen Schleu's) brilliant port of 3.2.1. Over a couple of years the AGS project moved on but I was unable to take advantage of the updates due to my old code. I finally decided to take on the task of updating my port to the latest version (3.3.3), as well as adding new fixes to problems that have arisen as the iOS operating system has grown and changed. The biggest problems were that Apple now requires a 64-bit build in anything submitted to the App Store, and recent changes to iOS have made the engine unstable, crashing more frequently than I am happy with.

I decided to keep an account of the process, because people keep asking me what I did to get a version of AGS that can be published on the App Store. Jochen's version was aimed at people with jailbroken iPhones who wanted to put their existing PC AGS game collection on iOS. This wasn't ideal for Wadjet Eye as it didn't have the signings necessary for submission to the App Store, and also the controls were designed to be universal, so that any AGS game could be played, which ended up feeling kind of clunky for the Wadjet Eye style of interface (which is classic Lucasarts inspired.)

My version of this can be found at:

https://github.com/JanetGilbert/ags

Branch name: iOS

Feel free to fork it to your own account for your own use; AGS is open source after all!

Code Signing
------------

You need to go to the Apple Developer website to set up the code signing and profiles.

https://developer.apple.com/

Enroll in the Apple Developer program ($99 a year). You can't really avoid opening your wallet at this point; you can fuss about with jailbroken devices and old versions of XCode if you really like headaches and never want anyone else to play your game. :-)

Go to the "Member Center", and the "Certificates, Identifiers & Profiles" section.

Go to "Certificates", and make yourself  "Development/iOS and App store" and "Production/App Store and Ad Hoc" certificates.

Go to "Identifiers" and add an App ID for your game (eg com.wadjeteyegames.YourGame)

Go to "Devices" and add the UDIDs for all devices you will be testing on personally. You used to have to add all beta tester UDIDs here, but Apple has now added a service called "Testflight" that makes this unnecessary. The UDID is the string under "Identifier" for your device if you open Windows/Devices from the XCode menu.

Go to "Provisioning Profiles" and make "iOS App Development", "App Store" and "Ad Hoc" profiles.

Go back to XCode. Open the XCode/Preferences menu item. Go to "Accounts" and click the "+" sign in the bottom left to add your Apple ID. Any time you make a change in Apple Developer, you need to come back to this page, click the "View Details" button, and then the refresh arrow in the bottom left of the details page. The profiles should then refresh. If some seem to be missing, leave it a while and try again. I am honestly not sure why sometimes this doesn't work. Sometimes exiting XCode and re-trying seems to help. It's magic. If anything ever goes wrong with compiling your game that doesn't make sense, refresh, clean and rebuild. Solves 90% of all possible problems.

Create a Project
----------------

Duplicate the ags project and open it in XCode (open ags.xcodeproj)

Rename the project to your project name. Slow double click on the name of the project in the top-left (just above something that says something like 1 target, iOS SDK 8.2). Type in your project name (eg YourGame). If you can't see the game name, click on the icon in the top left that looks like a folder. Don't ever rename the game in any other way; XCode needs to rename a bunch of internal things that get really borked if you try to edit the .xcodeproj in a text editor. I found out the hard way!

Click on the name of the project in the top left. You should now have a pane which has a project and a target, hopefully both called YourGame.

There are two sections in the middle horizontal column of the screen, one labelled "Project" and one labelled "Target", which should both be named "YourGame." This section is called "General Target Settings"

The "Project" is the game project overall, and the "Target" is a subset of that. I use multiple Targets to make different versions of a game with different files included, all in one big project. I use this feature often when making Mac games for Steam/non-Steam, but I've never made more than one Target for an iOS game. Some things need to be set in *both* "Project" and "Target", so if something doesn't seem to be taking effect, check that it is the same in both "Project" and "Target."

General Target Settings
-----------------------

*** Project ***

** Project Info **

Set iOS Deployment Target to 5.1.1. You have to enter this in the box manually. This version is significant because it allows you to retain compatibility with the iPhone 3G, and also use 64-bit builds. If you don't care about compatibility with older devices, set it higher.

** Project Build Settings **

* Architectures tab *
Architectures: Set this to $(ARCHS_STANDARD_INCLUDING_64_BIT)
Valid architectures: Set this to arm64 armv7

* Code Signing tab *

Set the Debug Code Signing Identities to your Developer ID, and the Release code signing identities to your Distribution ID.

Set the Debug Provisioning Profiles to your Ad Hoc profile, and the Release Provisioning Profiles to your game's Provisioning Profile.

Remove "-gta" from Other Code Signing Flags/Debug. This allows the app to be deployed on Jailbroken devices, but prevents it compiling to be released on the App Store.

*** Targets ***

** General **

* Identity tab *

Bundle identifier: Don't set here, set in "Info"
Version (CFBundleShortVersionString): The version of the game displayed to users. Try 1.0. Increase every time you publish a new version to the public. 
Build (CFBundleVersion): The internal build number. Increase by every time you publish externally (even to Testflight)

* App Icons and Launch Images tab *
Set up your icons here! You need to use an "Asset Catalogue"

Here are Apple's constantly-changing icon size/launch screen size requirements: https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/MobileHIG/IconMatrix.html

Ugh. They literally add more required images every iOS version update. This used to be nice and simple.

When you add the icon asset catalogue, you need to drag the appropriate sized icons to the box (from Finder.) This is like a cute little puzzle game. Watch out for the 2x and 3x sizes - this means that you need an icon 2 or 3 times the listed size (eg 57x57 x2 = 114x114)

The launch image asset catalogue is much the same, except it doesn't tell you the pixel sizes. Click on the icon in the top right that looks like a box with a vertical line on the right side. This gives you some stats including the expected size of the image.


** Info **

Ensure the Bundle Identifier is set to the same thing as in Member Center/Identifiers, and the Status Bar is initially hidden.

** Build Settings **


* Architectures tab *
Set "Architectures" and "Valid Architectures" to same as "Project"

* Code Signing tab *
Set "Code Signing Identity" and "Provisioning Profile" to same as "Project"

Remove "-gta" from Other Code Signing Flags/Debug. This was to allow the app to be deployed on Jailbroken devices, but prevents it compiling to be released on the App Store.


** Build Phases **

* Run script *

Remove the script relating to code signing (it begins "export CODESIGN_ALLOCATE" and ends "fi") - this is code allowing the engine to run on jailbroken devices and will interfere with compilation of a version that can be submitted the the App Store.

Schemes
-------

Schemes are necessary for compiling the game. At the very top of the screen, just to the right of the "Play" arrow button, there should be a label that still reads "ags". Click on "ags", then select "Manage Schemes" from the drop-down. Delete the "ags" scheme. Then use the "+" to create a scheme named "YourGame"


The Project Navigator
---------------------

This is the section of the screen to the left, where you renamed the project in the section "Create A Project." It has several views - ensure you are using the top-left view, by clicking on the top-left icon that looks like a single folder.

*** Resources ***

This section is what you will be looking at most often. You need to add the files ac2game.dat, audio.vox, speech.vox, ios_ipad.cfg, ios_iphone.cfg and any other data files your game requires. Add them by dragging from Finder.

ac2game.dat is just your windows .exe renamed. You can snip out the unnecessary executable parts by opening it in a hex editor and searching for the string "PADDING". There is a block of text that repeats "PADDINGXX" for a bit, then "CLIB". Chop out everything before CLIB (but leave CLIB). This saves a little space.

If you wish to make more than one variant of a game, you can create multiple targets, and include different resource files for each target. I find this very useful for OSX to make different builds for Steam and non-Steam.

* .cfg files *

Here's what I use (with the variants for iPad)

[misc]
config_enabled = 1
rotation = 2
translation = default
[controls]
mouse_method = 0
mouse_longclick = 1
[compatibility]
clear_cache_on_room_change = 0
[sound]
samplerate = 44100
enabled = 1
threaded = 0
cache_size = 10
[midi]
enabled = 1
preload_patches = 0
[video]
framedrop = 0
[graphics]
renderer = 0
smoothing = 1 (0 on iPad)
scaling = 1
super_sampling = 1 (0 on iPad)
smooth_sprites = 1 (0 on iPad)
[debug]
show_fps = 0
logging = 0

The variants for iPad produce a "blockier" more pixelated look that I like (but some people do not), as opposed to a blurred "anti-aliased" look that I prefer on the iPhone. Experimentation is key here to find out what works for your game.

Since there is only one (universal) build, I include settings files for both iPad and iPhone and select the right one at runtime.

Libraries
---------

The standard version of AGS has only 32-bit libraries. Apple no longer accepts builds without 64-bit libraries.Obtain these from me or just look in my fork of AGS (ios branch) and take them. There are also XCode projects for these libraries available in my fork of AGS if you need to recompile them.

Code Changes
------------

Here is an overview of the changes I made to the code to get Wadjet Eye Games running smoothly. My plan was to make them play as if they had been designed for touch-screen platforms, with no awkward work-arounds that betray their PC origins.

To see exactly what I did, take a look in my fork of AGS, "iOS" branch.

*** Path to game files ***

The game files are added in Resources, and copied over to the root of the iOS App. (YourGame.app.) This is not where AGS expects to find them.

The engine is still working under the assumption that you are running on a jailbroken device and you will manually copy over into the documents folder and select your game files. I remove the ability to select files, and just load the default file name (ac2game.dat) in the root folder.

*** Dragging and Dropping ***

("Drag'n'Drop")

This commit ("Drag'n'Drop") removes the ability to run standard PC AGS games in a jailbroken iPhone, (by removing the ability to right-click) but allows much finer control over touchscreen controls in script.

JJS designed the iOS controls to be one-finger-tap for left-click, and two-finger-tap for  right click. This was to allow existing PC versions of games to be played on iOS device.

I re-wrote the game script to use a verb-coin interface on iOS, making a right-click unnecessary.  The game script is able to tell when and where the user's finger is pressed to the screen, and when it is removed. This allows taps and tap-and-drags to be simulated in-code.

*** Tap past dialogue ***

("Tap past dialogue on mouse up, not down.", "More responsive dialogs")

The engine, by default, skips past dialog when you press your finger to the screen. I changed this to when you press and release, because the other way was accidentally activating the next dialog option.

*** Wadjet Eye Utils ***

("Added AGSWadjetUtils plugin")

This is a plugin that exposes some useful functions to the script.

FakeKeyPress() allows the script to pretend a key was pressed. This is used in Gemini Rue's combat system (which was key controlled on PC, button controlled on iOS) and for making a software keyboard (the built in keyboard does not look nice in a game, has some characters that AGS cannot display, and the close button is too small.)

It also has some functions for achievements, but I couldn't get them working. Anyone who wants to fix them up, tell me how you did it!

*** Cutscene skipping ***

("Cutscene skipping")

In PC AGS games, you skip cutscenes by pressing "Esc". Lacking a keyboard, I needed some other way. It needed to be something implemented at engine level because the script is blocked in cutscenes.

I first experimented by skipping cutscenes with a long press (hold the finger to the screen for a long time) but it was too easy to activate. So I hit upon swiping the finger from left to right at the top of the screen.

I'm not sure how many players use this feature, since most adventure games get played only once, due to being roughly the same each time. It was more a feature for debug (It gets OLD watching the same cutscenes every game) which I left in for people to use or not, depending on whether they remembered it existed.

*** Set Mouse Position ***

("Fixed mouse position")

Simple fix to the scaling of the mouse position. Without it, you can't correctly set the mouse position from script. I use this to place the cursor neatly in the middle of the screen when you change scenes.

*** Config Files ***

("Load different config files for iPhone and iPad")

ios_ipad.cfg is loaded on iPad, and ios_iphone.cfg on iPhone. The difference is in the scaling and smoothing settings, to give an "anti-aliased" effect on iPhone and a sharp, pixelated effect on iPad.


*** Misc bugs & bug-ettes ***

Small, but important.

("Memory leak in ReadString")
("Sound crash bug fix")
("Dismiss Display() boxes on mouse up, not mouse down")
("Fake keypress support")
("Hide status bar")
("Move iOS-specific classes")
("Bug: Keypress not detected")
("Restore audio after phone call")
("Crude hack to restore audio after answering phone call")


*** 64-bit ***

This was a beast of a bug. Apple introduced a requirement that all games must include a 64-bit build, but that meant that I needed to recompile all the dependencies with a 64-bit slice. The last time the libraries were compiled was in Ye Olde Times by JJS.

The system that JJS used to compile the libraries was called cmake. He wrote scripts for this that simultaneously patched the library code (with his bug fixes) and built them. Unfortunately the latter half of the process (building) was very outdated and no longer worked.

The system I came up with was to comment out the building portion of the scripts and just run the patching portion (see my commit "Allegro patch only"). Don't forget to use chmod u+x to get permission to run the scripts (which are in the ags\ios\buildlibs\armv7 folder)

I then made the resulting source files into an XCode project, and built the library as a Cocoa Touch Static Library. I built it for the required architectures armv7 and arm64. Set "Always search user paths" in "Build Settings" to "Yes" and set "User Header Search Paths" to "${SOURCE_ROOT}/[LIBNAME]/include ${SOURCE_ROOT}/../../nativelibs/fat/include" (or whatever needed) or else you will get errors like "Lexical or preprocessor issue 'internal/it.h' file not found" (double-click on the paths and ensure they are recursive). Remove the autogenerated files called something like allegro.h and allegro.m from the project or else you get a lot of errors like "Semantic Issue: Unknown type name 'NSString'". "Product->Destination" must be a real iOS device you have plugged into the computer, or else the Product will not be created even though the build apparently succeeds.

Then I encountered a different problem. I added the resulting library to my project and I got errors complaining "Undefined symbols for architecture x86_64" which turned out to mean that XCode expects a library containing both iOS device architectures (armv7, arm64) AND iOS simulator (i386, x86_64) architectures.

Unfortunately XCode can't build all these simultaneously in one library. You need to build for both device and simulator separately, then combine them using a command-line tool called "lipo"

First: build for device (Product->Build For->Running) THEN build for simulator (Product->Build For->Testing). Note that by default the  "Run" scheme is Debug, which you don't really want. So "Edit Schemes" and on the "Info" tab for "Run", set the "Build Configuration" to "Release". To build for simulator, you must set a simulator as "Destination"

Then use lipo to combine the two in the following way.

lipo -create Release-iphoneos/liballegro.a Release-iphonesimulator/liballegro.a -output liballeg.a

Use lipo to test success:

lipo -info liballeg.a

Desired result: Architectures in the fat file: liballeg.a are: armv7 i386 x86_64 arm64

Next
----

That should give you a working version of the AGS engine, but you still need to alter the script of your game to work with the engine. The most important thing to do is to remove all instances of needing to right-click in the game, because if you followed my instructions, you can now only left-click by tapping on the screen. I'll write a post in the future describing the process I go through to update the script of our AGS games to work well with iOS.

Feel free to email me with any questions at janet@wadjeteyegames.com. AGS is open source, and so is my fork, so you can fork it yourself if you want, or use any of my alterations freely.


https://github.com/JanetGilbert/ags

Branch name: iOS

Well, I finally got the iOS engine building for 64-bit! Now to test it and hopefully release some games!

Hi, I'm Janet from Wadjet Eye.

For various reasons I have a ticket for GDC that I can't use *sob*

I'd like to give it to someone else from the AGS community to give back a little for all the wonderful things you have done for us over the years.

The ticket is for the Summits on Monday and Tuesday next week. (2nd & 3rd of March). NOT the Main Conference.

Note that the ticket does not include flight or accomodation, so please only ask for this if you are able to get to San Francisco easily next week.

I always find the summits to be the most interesting and initimate part of the conference. They tend to be small talks in small rooms with good chances to get to know your fellow attendees. The narrative game track and the indie game track are particularly relevant to adventure games. Its great for networking if you are trying to get into the game industry.

PM me!

Janet

We're also running into this problem. It might be worth looking for someone on Elance.com ?

I would prefer a personal recommendation so I can be sure the developer is competent and can work with an existing codebase. There's a lot of sleazy iOS developers out there because of the "gold rush" nature of the platform. Trust me, I get spammed by them every day!

Does anyone know a commercial iOS contractor that would be interested in low-level engine stuff?

Without JJS I really don't know how to keep AGS up to date for more recent version of iOS. I have been in contact with JJS but he is too busy to work on the code right now.

Wadjet Eye Games is willing to pay a professional to update the port. We need it to work properly with iOS 8. Currently it crashes a lot and can't be built as 64-bit (which Apple are requiring for uploads to the App store)

Can anyone recommend a contractor to do this? They'd need to be experienced in low-level iOS code.

Thanks!

Janet

janet@wadjeteyegames.com

Our other option is to have detailed build instructions for lots of different platforms, and WadjetEye can just provide the game data files. BYOE style.

Not for a commercial game - that would be fine for freeware. People already do that by buying the PC version and compiling the Linux runtime for their platform.

I've noticed that games forked from my version are reporting to my Crashlytics account. Could you turn off that feature or redirect it to your own Crashlytics account please?

To do this, search the code for Crashlytics and remove those things, remove the Crashlytics framework, and also remove from the "Run Script" phase.

To clarify, I'm talking about the Humble bundle port, not the main project that you guys are working on. The Humble bundle version is ready to go (in terms of code.) I'm not asking BigMc to change the code in the main AGS project at all. I just don't know how to compile in terms of a commercial-ready release. I have compiled it just fine with the instructions at:

https://github.com/adventuregamestudio/ags/blob/master/debian/README.md

But that does not produce something I can package for release. I am wondering where to go from there.

I'm not familiar with Linux at all, so I'm not really understanding this thread in more than superficial terms. For instance I don't know if I want to use the ags+libraries script because I am not clear on what it does. I think I need some examples of a method to build a commercial-quality game to start from. People here are being very helpful in terms of "If you want X, you should do Y and Z," but I'm more stuck on whether I want to do X or something else, and why.

I know that Scott produced a commercial-quality build of Gemini Rue for us a while back (which never ended up getting released for various reasons) so I would be eager to know the method he used.

Thanks, but the script says it should only be used on Debian, not Ubuntu, and I installed Ubuntu.

Is there a simple way to build a Linux application for most commonly used Linux versions? This all seems fantastically complicated. I feel I am going to end up maintaining 7+ compiled versions of each game for Linux and installing multiple versions of Linux just to build with. Am I wrong? For a small market it may simply be too fragmented to be worth it, unfortunately

deb and rpm packages have the advantage that they can be cleanly deinstalled later, but you still need something else in addition because not every distribution has deb or rpm.

What I like most is a tar.gz where you can decide if you want to start the game immediately after extracting or run an install script that copies the game and a .desktop file somewhere else so that you have a menu entry.
It's nice if the script is short and simple so that you can have a look at it before running it. That also helps with uninstalling.

If you look at the Humble Bundles, games often have multiple options, for example deb + rpm + something for all distributions.

I have no experience using Linux. I installed it for the first time yesterday. I'm trying to understand expectations that are very obvious to people who have been using Linux for years (such as the differences between the different distributions of Linux.)

So, tar.gz files have scripts that allow you to set up install locations? How does one set this up?

What is the best way of building AGS on Linux to make a simple package that contains game files? The instructions on Github assume that you are wanting to load multiple game files that you have obtained elsewhere. I want to produce something like the Gemini Rue package that the Humble Bundle guys produced - it just runs one game.

What is a deb and rpm package?

I would personally like a manual save option, where you can list each item you want saved, and everything else remains as default.

For commercial games, it is hard to fix bugs without users saves being trashed.

A lot of Linux people are "Old-school" so if what Linux users like is "No installer" I'm happy to save myself some work

Any linux-users here want to say "No, I really do like installers!"?

Hey guys,

Since we now have a commercial-ready Linux port courtesy of the Humble Bundle, I want to release Wadjet Eye's games on Linux as soon as possible. What's the Linux community preferred way of building an installer for games?

Janet

Thanks, CrimsonWizard! That worked.

[error: The requested URL returned error: 403 while accessing https://github.com/humble/ags-geminirue.git/info/refsfatal: HTTP request failed]

! [rejected]        humble-ports -> humble-ports (non-fast-forward)
error: failed to push some refs to 'git@github.com:JanetGilbert/ags.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart.

Error like this indicates that there were changes to remote that are not found in your local branch. Don't know how it happened to be. Maybe you have two local repositories, or something like that?
On usual occasion this is solved by making a "git pull" before doing anything else.

No, no local changes. "git pull" responds that there are no changes.

If I instead try using the terminal, I get a different error after using git push:

error: The requested URL returned error: 403 while accessing https://github.com/humble/ags-geminirue.git/info/refs
fatal: HTTP request failed

Which address do you use in git command? It should be just "https://github.com/humble/ags-geminirue.git" instead.

I did exactly what you suggested in your post above. I don't know where the "info/refs" came from.

[! [rejected] humble-ports -> humble-ports (non-fast-forward)error: failed to push some refs to 'git@github.com:JanetGilbert/ags.git'hint: Updates were rejected because the tip of your current branch is behindhint: its remote counterpart.]

Well, my baby is at her grandmothers for the day so I finally got a chance to try this! But it didn't work

It seemed to work, but when I try to use Github for Mac to commit changes, it commits them and then doesn't remove the commit from the list of unsynced commits. When I try to commit again, it gives me this error message:

! [rejected]        humble-ports -> humble-ports (non-fast-forward)
error: failed to push some refs to 'git@github.com:JanetGilbert/ags.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart.


If I instead try using the terminal, I get a different error after using git push:

error: The requested URL returned error: 403 while accessing https://github.com/humble/ags-geminirue.git/info/refs
fatal: HTTP request failed

(the password and user name I supplied to git push were correct)

What could I be doing wrong?

Thanks,

Janet

Thanks guys. I'll do this as soon as my baby takes a good, solid nap tomorrow!

I use a simple GUI but it can't do anything complicated, so I use the command line for most things more complicated than committing or branching.

This is really a git question, I suppose, but is it possible to get the repository exactly as Edward left it so I can compile Wadjet Eye's other games for Mac and Linux? I have my own fork of the repository which is not really compatible with anyone elses (for iOS) and I don't want to overwrite or merge it.

Hi, HumbleBundle ported the AGS engine to Mac so that we could have Gemini Rue on the Humble Bundle With Android (it's up now! So exciting!)

This means we now have a working port to Mac, and it's still Open Source, of course!

Where do you guys want it put?

Regarding this new port, we would need to see the code to compare changes and learn what needs to be done to make a merge. Is the code still originate from ags repository you have? In this case you could probably submit it as a separate branch to your personal repository on github.

It is not related to my AGS repository, which is heavily mucked about with to make mobile games. It is derived from the main AGS port at:

https://github.com/adventuregamestudio/ags

Is there a way that the porting engineer (Edward) could push his changes back there to a separate branch? I assume we want to use his changes if we can, to make the port native Mac compatible from now onward. I'm not an expert on Git. Is this a good idea? Would he need permissions to do this?

The port also contains fixes to Linux which were made for the commercial release of Gemini Rue on that platform.