pygame-ios 0.0.5

Run pygame-ce games on iPhones and iPads easily.

Disclaimer

This library is not well tested, and shouldn't be considered production ready. Most importantly, I haven't tested App Store builds yet.

There's still a lot of work to be done and I'm working on documenting what's doable and what's not.

---

pygame-ios

Run pygame-ce games on iPhones and iPads easily.

This package contains a simple CLI tool that downloads a template from pygame-ios-templates and adds your game files to it. After that you can run the Xcode project and see your pygame-ce game on your device or simulator of choice.

Usage

To use this package, you need macOS, and you need Xcode and Python 3 installed.

Run this to install the package:

pip install pygame-ios

This gives you a command you can run with one of the following:

pygame_ios
python -m pygame_ios

Notice the underscore. Type pygame_ios, not pygame-ios.

This command needs arguments. You need to provide a location for your project folder where your files will be copied from, as well as an entry point script which will be renamed to __main__.py and used as the entry point in Xcode. You must also specify the pygame-ce version.

Example usage:

pygame_ios . game.py 2.5.6 # copies files from current folder, uses game.py as the entry point script, pygame-ce v2.5.6

After running this command, an Xcode project will be downloaded. You can open this project in Xcode and run it on a device or simulator.

To update your Xcode project with new files or changes, just run the command again. The download step is skipped and your files are copied, overwriting previous files.

It's recommended that you modify the Xcode project directly if you want to change metadata like the product name and icon, and add it to source control. You cannot recover these changes if you delete the project, like you might be able to in other libraries like Briefcase or Flutter.

Not all pygame-ce versions are supported, see here for supported versions, and see the repository README for details on how to make your own.

Other Arguments

If you have a template .zip file on your machine, you can specify a path to that file instead of downloading one:

pygame_ios . game.py 2.5.6 ./template/your-template.zip

This is useful for custom templates, or if you just want to reduce network use.

It's assumed that this template has the same folder structure as a template from pygame-ios-templates. The version number is also ignored if you specify a local path.

Installing Packages with pip install

You can install pure Python packages into the Xcode template using the --target flag. For example with pytmx:

pip install --target ./pygame-ios-template/pygame-ios/app_packages.iphoneos pytmx
pip install --target ./pygame-ios-template/pygame-ios/app_packages.iphonesimulator pytmx

I recommend using a Python version that matches the XCFramework in the template, which is 3.13 as of time of writing.

Binary modules are a lot more complicated. You would need to find wheels that are already built for iOS (for example in the BeeWare Anaconda repository, which is where the numpy build comes from) or build those packages yourself using largely undocumented methods of building for iOS.

Polling Events on iOS

Pygame apps typically use a pattern like this to poll events and run per-frame logic:

while True:
	for event in pygame.event.get():
		if event.type == pygame.QUIT:
			sys.exit(0)

	pygame.display.flip()

This will continue to work on iOS, but it will block the main thread. This becomes a problem if you want to display any native iOS controls, like opening the Game Center dashboard. These native controls will likely hang the app.

To get around this, pygame-ios allows you to poll events like this instead:

def tick():
	for event in pygame.event.get():
		if event.type == pygame.QUIT:
			sys.exit(0)

	pygame.display.flip()

_ios_tick = tick

The _ios_tick variable must be defined at the most outer scope of your entry point script, outside any methods and classes. The pygame-ios template code will find your function and use SDL_iPhoneSetAnimationCallback to add it to the native iOS run loop. This allows you to poll events without blocking the main thread.