Metadata-Version: 2.4
Name: pygame-ios
Version: 0.0.5
Summary: Run pygame-ce games on iPhones and iPads easily.
Author-email: Luke Lazzaro <lazzdev@proton.me>
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-Expression: MIT
License-File: LICENSE
Requires-Dist: requests
Project-URL: Homepage, https://github.com/seekerluke/pygame-ios
Project-URL: Issues, https://github.com/seekerluke/pygame-ios/issues

# 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.

---

![screenshot](pygame-ios.png)

# 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](https://github.com/seekerluke/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:

```bash
pip install pygame-ios
```

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

```bash
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:

```bash
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](https://github.com/seekerluke/pygame-ios-templates/blob/main/patches/pygame-ce.json) for supported versions, and see the [repository README](https://github.com/seekerluke/pygame-ios-templates?tab=readme-ov-file#making-new-templates) 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:

```bash
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](https://github.com/seekerluke/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:

```bash
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](https://anaconda.org/beeware/repo), 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:

```python
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:

```python
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.

